Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
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
docs/source/code.rst
View file @
ae36ab9d
.. currentmodule:: nifty4
.. currentmodule:: nifty4
=============
Code Overview
Code Overview
=============
=============
Executive summary
=================
The fundamental building blocks required for IFT computations are best
The fundamental building blocks required for IFT computations are best
recognized from a large distance, ignoring all technical details.
recognized from a large distance, ignoring all technical details.
...
@@ -190,7 +195,7 @@ Syntactic sugar
...
@@ -190,7 +195,7 @@ Syntactic sugar
Nifty4 allows simple and intuitive construction of altered and combined
Nifty4 allows simple and intuitive construction of altered and combined
operators.
operators.
As an example, if ``A``, ``B`` and ``C`` are of type :class:`LinearOperator`
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
X = A*B.inverse*A.adjoint + C
f2 = X(f1)
f2 = X(f1)
...
@@ -206,6 +211,7 @@ were the original operator's adjoint or inverse, respectively.
...
@@ -206,6 +211,7 @@ were the original operator's adjoint or inverse, respectively.
.. _minimization:
.. _minimization:
Minimization
Minimization
============
============
...
@@ -224,9 +230,15 @@ Function values are floating-point scalars, gradients have the form of fields
...
@@ -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
living on the energy's position domain, and curvatures are represented by
linear operator objects.
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
Iterative minimization of an energy reqires some means of
controlling the quality of the current solution estimate and stopping once
controlling the quality of the current solution estimate and stopping once
...
@@ -250,6 +262,36 @@ for their specific applications.
...
@@ -250,6 +262,36 @@ for their specific applications.
Minimization algorithms
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
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
used for minimizing IFT Hamiltonians, but also for the numerical inversion of
linear operators, if the desired application mode is not directly available.
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
...
@@ -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
of NIFTy's :class:`InversionEnabler` class, which internally performs a
minimization of a :class:`QuadraticEnergy` by means of a
minimization of a :class:`QuadraticEnergy` by means of a
:class:`ConjugateGradient` algorithm.
: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()):
...
@@ -70,16 +70,18 @@ class Energy(NiftyMetaBase()):
@
property
@
property
def
position
(
self
):
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.
The Field location in parameter space where value, gradient and
curvature are evaluated.
"""
"""
return
self
.
_position
return
self
.
_position
@
property
@
property
def
value
(
self
):
def
value
(
self
):
"""
"""
float : value of the functional
float : value of the functional.
The value of the energy functional at given `position`.
The value of the energy functional at given `position`.
"""
"""
raise
NotImplementedError
raise
NotImplementedError
...
@@ -102,7 +104,7 @@ class Energy(NiftyMetaBase()):
...
@@ -102,7 +104,7 @@ class Energy(NiftyMetaBase()):
@
property
@
property
def
curvature
(
self
):
def
curvature
(
self
):
"""
"""
LinearOperator : implicitly defined curvature
LinearOperator : implicitly defined curvature
.
A positive semi-definite operator or function describing the
A positive semi-definite operator or function describing the
curvature of the potential at the given `position`.
curvature of the potential at the given `position`.
"""
"""
...
...
nifty4/minimization/minimizer.py
View file @
ae36ab9d
...
@@ -23,6 +23,7 @@ from ..utilities import NiftyMetaBase
...
@@ -23,6 +23,7 @@ from ..utilities import NiftyMetaBase
class
Minimizer
(
NiftyMetaBase
()):
class
Minimizer
(
NiftyMetaBase
()):
""" A base class used by all minimizers."""
""" A base class used by all minimizers."""
# MR FIXME: the docstring is partially ignored by Sphinx. Why?
@
abc
.
abstractmethod
@
abc
.
abstractmethod
def
__call__
(
self
,
energy
,
preconditioner
=
None
):
def
__call__
(
self
,
energy
,
preconditioner
=
None
):
""" Performs the minimization of the provided Energy functional.
""" Performs the minimization of the provided Energy functional.
...
@@ -30,17 +31,15 @@ class Minimizer(NiftyMetaBase()):
...
@@ -30,17 +31,15 @@ class Minimizer(NiftyMetaBase()):
Parameters
Parameters
----------
----------
energy : Energy
energy : Energy
Energy object which provides value, gradient and curvature at a
Energy object at the starting point of the iteration
specific position in parameter space.
preconditioner : LinearOperator, optional
preconditioner : LinearOperator, optional
Preconditioner to accelerate the minimization
Preconditioner to accelerate the minimization
Returns
Returns
-------
-------
Energy
Energy : Latest `energy` of the minimization.
Latest `energy` of the minimization.
int : exit status of the minimization
int
Can be controller.CONVERGED or controller.ERROR
exit status of the minimization
"""
"""
raise
NotImplementedError
raise
NotImplementedError
nifty4/minimization/nonlinear_cg.py
View file @
ae36ab9d
...
@@ -22,13 +22,17 @@ from .line_search_strong_wolfe import LineSearchStrongWolfe
...
@@ -22,13 +22,17 @@ from .line_search_strong_wolfe import LineSearchStrongWolfe
class
NonlinearCG
(
Minimizer
):
class
NonlinearCG
(
Minimizer
):
""" Implementation of the nonlinear Conjugate Gradient scheme according to
""" Nonlinear Conjugate Gradient scheme according to Polak-Ribiere.
Polak-Ribiere.
Algorithm 5.4 from Nocedal & Wright.
Eq. (5.41a) has been replaced by eq. (5.49)
Parameters
Parameters
----------
----------
controller : IterationController
controller : IterationController
Object that decides when to terminate the minimization.
Object that decides when to terminate the minimization.
line_searcher : LineSearch, optional
The line search algorithm to be used
References
References
----------
----------
...
@@ -41,21 +45,6 @@ class NonlinearCG(Minimizer):
...
@@ -41,21 +45,6 @@ class NonlinearCG(Minimizer):
self
.
_line_searcher
=
line_searcher
self
.
_line_searcher
=
line_searcher
def
__call__
(
self
,
energy
):
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
controller
=
self
.
_controller
status
=
controller
.
start
(
energy
)
status
=
controller
.
start
(
energy
)
if
status
!=
controller
.
CONTINUE
:
if
status
!=
controller
.
CONTINUE
:
...
...
Write
Preview
Supports
Markdown
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