Commit ae36ab9d authored by Martin Reinecke's avatar Martin Reinecke

more documentation

parent 6480d0a5
Pipeline #25125 passed with stages
in 8 minutes and 57 seconds
.. 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
......@@ -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`.
"""
......
......@@ -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
......@@ -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:
......
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