Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Open sidebar
ift
NIFTy
Commits
ae36ab9d
Commit
ae36ab9d
authored
Feb 19, 2018
by
Martin Reinecke
Browse files
more documentation
parent
6480d0a5
Pipeline
#25125
passed with stages
in 8 minutes and 57 seconds
Changes
4
Pipelines
1
Hide whitespace changes
Inline
Side-by-side
Showing
4 changed files
with
63 additions
and
47 deletions
+63
-47
docs/source/code.rst
docs/source/code.rst
+45
-19
nifty4/minimization/energy.py
nifty4/minimization/energy.py
+7
-5
nifty4/minimization/minimizer.py
nifty4/minimization/minimizer.py
+5
-6
nifty4/minimization/nonlinear_cg.py
nifty4/minimization/nonlinear_cg.py
+6
-17
No files found.
docs/source/code.rst
View file @
ae36ab9d
.. 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
View file @
ae36ab9d
...
...
@@ -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`.
"""
...
...
nifty4/minimization/minimizer.py
View file @
ae36ab9d
...
...
@@ -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
View file @
ae36ab9d
...
...
@@ -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
:
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment