diff --git a/docs/source/code.rst b/docs/source/code.rst
index cff7a095c98a3a89b0d4245412adf70ec703c3b0..e19b4e1df8c2869c229698cde54aec965fddd574 100644
--- a/docs/source/code.rst
+++ b/docs/source/code.rst
@@ -1,8 +1,13 @@
.. 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
-
diff --git a/nifty4/minimization/energy.py b/nifty4/minimization/energy.py
index 60f4cf294b66e8860431285a3d67a51ff4cfc364..8a436981424b9bf0c8d8bc0925a52d0b150d5eb8 100644
--- a/nifty4/minimization/energy.py
+++ b/nifty4/minimization/energy.py
@@ -70,16 +70,18 @@ class Energy(NiftyMetaBase()):
@property
def position(self):
"""
- Field : selected location in parameter space
- The Field location in parameter space where value, gradient and
- curvature are evaluated.
+ Field : selected location in parameter space.
+
+ The Field location in parameter space where value, gradient and
+ curvature are evaluated.
"""
return self._position
@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`.
"""
diff --git a/nifty4/minimization/minimizer.py b/nifty4/minimization/minimizer.py
index ac17c173caa1d4235c1d56f9c9eeec3bcd25c460..e98412c871ba1750108d06f2e2672534d593b355 100644
--- a/nifty4/minimization/minimizer.py
+++ b/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
diff --git a/nifty4/minimization/nonlinear_cg.py b/nifty4/minimization/nonlinear_cg.py
index dc2d249f48307d65fca9132566fb98fb2e2ca7e0..2cc638b4df7ad56617c492f6b10f84130e1c3628 100644
--- a/nifty4/minimization/nonlinear_cg.py
+++ b/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: