more documentation

docs/source/code.rst

 .. currentmodule:: nifty4
 
+=============
 Code Overview
 =============
 
+
+Executive summary
+=================
+
 The fundamental building blocks required for IFT computations are best
 recognized from a large distance, ignoring all technical details.
 
@@ -190,7 +195,7 @@ Syntactic sugar
 Nifty4 allows simple and intuitive construction of altered and combined
 operators.
 As an example, if ``A``, ``B`` and ``C`` are of type :class:`LinearOperator`
-and ``f1`` and ``f2`` are :class:`Field` s, writing::
+and ``f1`` and ``f2`` are of type :class:`Field`, writing::
 
     X = A*B.inverse*A.adjoint + C
     f2 = X(f1)
@@ -206,6 +211,7 @@ were the original operator's adjoint or inverse, respectively.
 
 .. _minimization:
 
+
 Minimization
 ============
 
@@ -224,9 +230,15 @@ Function values are floating-point scalars, gradients have the form of fields
 living on the energy's position domain, and curvatures are represented by
 linear operator objects.
 
+Some examples of concrete energy classes delivered with NIFTy4 are
+:class:`QuadraticEnergy` (with position-independent curvature, mainly used with
+conjugate gradient minimization) and :class:`~nifty4.library.WienerFilterEnergy`.
+Energies are classes that typically have to be provided by the user when
+tackling new IFT problems.
 
-Convergence control
--------------------
+
+Iteration control
+-----------------
 
 Iterative minimization of an energy reqires some means of
 controlling the quality of the current solution estimate and stopping once
@@ -250,6 +262,36 @@ for their specific applications.
 Minimization algorithms
 -----------------------
 
+All minimization algorithms in NIFTy inherit from the abstract
+:class:`Minimizer` class, which presents a minimalistic interface consisting
+only of a :meth:`~Minimizer.__call__` method taking an :class:`Energy` object
+and optionally a preconditioning operator, and returning the energy at the
+discovered minimum and a status code.
+
+For energies with a quadratic form (i.e. which
+can be expressed by means of a :class:`QuadraticEnergy` object), an obvious
+choice of algorithm is the :class:`ConjugateGradient` minimizer.
+
+A similar algorithm suited for nonlinear problems is provided by
+:class:`NonlinearCG`.
+
+Many minimizers for nonlinear problems can be described as
+
+- first deciding on a direction for the next step
+- then finding a suitable step length along this direction, resulting in the
+  next energy estimate.
+
+This family of algorithms is encapsulated in NIFTy's :class:`DescentMinimizer`
+class, which currently has three concrete implementations:
+:class:`SteepestDescent`, :class:`VL_BFGS`, and :class:`RelaxedNewton`.
+Of these algorithms, only :class:`RelaxedNewton` requires the energy object to
+provide a :attr:`~Energy.curvature` property, the others only need energy
+values and gradients.
+
+
+Application to operator inversion
+---------------------------------
+
 It is important to realize that the machinery presented here cannot only be
 used for minimizing IFT Hamiltonians, but also for the numerical inversion of
 linear operators, if the desired application mode is not directly available.
@@ -262,19 +304,3 @@ application is straightforward; to use it in forward direction, we make use
 of NIFTy's :class:`InversionEnabler` class, which internally performs a
 minimization of a :class:`QuadraticEnergy` by means of a
 :class:`ConjugateGradient` algorithm.
-
-Some examples of concrete energy classes delivered with NIFTy4 are
-:class:`QuadraticEnergy` (with position-independent curvature, mainly used with
-conjugate gradient minimization) and :class:`WienerFilterEnergy`.
-Energies are classes that typically have to be provided by the user when
-tackling new IFT problems.
-
-The minimization procedure can be carried out by one of several algorithms;
-NIFTy4 currently ships solvers based on
-
-- the conjugate gradient method (for quadratic energies)
-- the steepest descent method
-- the VL-BFGS method
-- the relaxed Newton method, and
-- a nonlinear conjugate gradient method
-

nifty4/minimization/energy.py

@@ -70,7 +70,8 @@ class Energy(NiftyMetaBase()):
     @property
     def position(self):
         """
-        Field : selected location in parameter space
+        Field : selected location in parameter space.
+
         The Field location in parameter space where value, gradient and
         curvature are evaluated.
         """
@@ -79,7 +80,8 @@ class Energy(NiftyMetaBase()):
     @property
     def value(self):
         """
-        float : value of the functional
+        float : value of the functional.
+
             The value of the energy functional at given `position`.
         """
         raise NotImplementedError
@@ -102,7 +104,7 @@ class Energy(NiftyMetaBase()):
     @property
     def curvature(self):
         """
-        LinearOperator : implicitly defined curvature
+        LinearOperator : implicitly defined curvature.
             A positive semi-definite operator or function describing the
             curvature of the potential at the given `position`.
         """

nifty4/minimization/minimizer.py

@@ -23,6 +23,7 @@ from ..utilities import NiftyMetaBase
 class Minimizer(NiftyMetaBase()):
     """ A base class used by all minimizers."""
 
+    # MR FIXME: the docstring is partially ignored by Sphinx. Why?
     @abc.abstractmethod
     def __call__(self, energy, preconditioner=None):
         """ Performs the minimization of the provided Energy functional.
@@ -30,17 +31,15 @@ class Minimizer(NiftyMetaBase()):
         Parameters
         ----------
         energy : Energy
-           Energy object which provides value, gradient and curvature at a
-           specific position in parameter space.
+           Energy object at the starting point of the iteration
 
         preconditioner : LinearOperator, optional
            Preconditioner to accelerate the minimization
 
         Returns
         -------
-        Energy
-            Latest `energy` of the minimization.
-        int
-            exit status of the minimization
+        Energy : Latest `energy` of the minimization.
+        int : exit status of the minimization
+            Can be controller.CONVERGED or controller.ERROR
         """
         raise NotImplementedError

nifty4/minimization/nonlinear_cg.py

@@ -22,13 +22,17 @@ from .line_search_strong_wolfe import LineSearchStrongWolfe
 
 
 class NonlinearCG(Minimizer):
-    """ Implementation of the nonlinear Conjugate Gradient scheme according to
-        Polak-Ribiere.
+    """ Nonlinear Conjugate Gradient scheme according to Polak-Ribiere.
+
+    Algorithm 5.4 from Nocedal & Wright.
+    Eq. (5.41a) has been replaced by eq. (5.49)
 
     Parameters
     ----------
     controller : IterationController
         Object that decides when to terminate the minimization.
+    line_searcher : LineSearch, optional
+        The line search algorithm to be used
 
     References
     ----------
@@ -41,21 +45,6 @@ class NonlinearCG(Minimizer):
         self._line_searcher = line_searcher
 
     def __call__(self, energy):
-        """ Runs the conjugate gradient minimization.
-        Algorithm 5.4 from Nocedal & Wright
-        Eq. (5.41a) has been replaced by eq. (5.49)
-
-        Parameters
-        ----------
-        energy : Energy object at the starting point of the iteration.
-
-        Returns
-        -------
-        Energy
-            state at last point of the iteration
-        int
-            Can be controller.CONVERGED or controller.ERROR
-        """
         controller = self._controller
         status = controller.start(energy)
         if status != controller.CONTINUE: