From 80ff8fdcb5d655aed1b8f8dd59a4e21ed9ffb0a9 Mon Sep 17 00:00:00 2001 From: Theo Steininger Date: Thu, 18 May 2017 09:13:30 +0200 Subject: [PATCH] Updated energy and minimization docstrings. --- .gitignore | 102 +++++++++++-- nifty/energies/energy.py | 79 ++++++---- nifty/energies/line_energy.py | 57 ++++---- nifty/minimization/.DS_Store | Bin 6148 -> 0 bytes nifty/minimization/conjugate_gradient.py | 76 +++++----- nifty/minimization/descent_minimizer.py | 106 +++++++------- nifty/minimization/relaxed_newton.py | 38 ++--- nifty/minimization/steepest_descent.py | 36 ++--- nifty/minimization/vl_bfgs.py | 175 +++++++++-------------- 9 files changed, 363 insertions(+), 306 deletions(-) delete mode 100644 nifty/minimization/.DS_Store diff --git a/.gitignore b/.gitignore index f1ff5797..f2515d0a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,18 +1,98 @@ -*.html +# custom +setup.cfg +.idea +.DS_Store + +# from https://github.com/github/gitignore/blob/master/Python.gitignore + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions *.c *.o *.so -*.pyc -*.log + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.installed.cfg *.egg -*.egg-info -*~ -.git/ -.svn/ -.spyderproject -.document -build +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec -.idea +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ .coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*,cover +.hypothesis/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# IPython Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule + +# dotenv +.env + +# virtualenv +venv/ +ENV/ + +# Spyder project settings +.spyderproject + +# Rope project settings +.ropeproject \ No newline at end of file diff --git a/nifty/energies/energy.py b/nifty/energies/energy.py index 9e602484..851f201e 100644 --- a/nifty/energies/energy.py +++ b/nifty/energies/energy.py @@ -22,44 +22,44 @@ from keepers import Loggable class Energy(Loggable, object): - """ The Energy object provides the structure required for minimization schemes. + """ Provides the functional used by minimization schemes. - The implementation of a scalar function with its gradient and curvature at some position. + The Energy object is an implementation of a scalar function including its + gradient and curvature at some position. Parameters ---------- - position : Field, float - The parameter of the scalar function and its first and second derivative. + position : Field + The input parameter of the scalar function. Attributes ---------- - position : Field, float - The Field location in parameter space where value, gradient and curvature is evaluated. - value : float - The evaluation of the energy functional at given position. - gradient : Field, float - The gradient at given position in parameter direction. - curvature : callable - A positive semi-definite operator or function describing the curvature of the potential - at given position. - - Raises - ------ - NotImplementedError - Raised if - * value, gradient or curvature is called - AttributeError - Raised if - * copying of the position fails + position : Field + The Field location in parameter space where value, gradient and + curvature are evaluated. + value : np.float + The value of the energy functional at given `position`. + gradient : Field + The gradient at given `position` in parameter direction. + curvature : LinearOperator, callable + A positive semi-definite operator or function describing the curvature + of the potential at the given `position`. Notes ----- - The Energy object gives the blueprint how to formulate the model in order to apply - various inference schemes. The functions value, gradient and curvature have to be - implemented according to the concrete inference problem. + An instance of the Energy class is defined at a certain location. If one + is interested in the value, gradient or curvature of the abstract energy + functional one has to 'jump' to the new position using the `at` method. + This method returns a new energy instance residing at the new position. By + this approach, intermediate results from computing e.g. the gradient can + safely be reused for e.g. the value or the curvature. - Memorizing the evaluations of some quantities minimizes the computational effort - for multiple calls. + Memorizing the evaluations of some quantities (using the memo decorator) + minimizes the computational effort for multiple calls. + + See also + -------- + memo """ @@ -74,7 +74,7 @@ class Energy(Loggable, object): self._position = position def at(self, position): - """ Initializes and returns new Energy object at new position. + """ Initializes and returns a new Energy object at the new position. Parameters ---------- @@ -87,20 +87,43 @@ class Energy(Loggable, object): Energy object at new position. """ + return self.__class__(position) @property def position(self): + """ + The Field location in parameter space where value, gradient and + curvature are evaluated. + + """ + return self._position @property def value(self): + """ + The value of the energy functional at given `position`. + + """ + raise NotImplementedError @property def gradient(self): + """ + The gradient at given `position` in parameter direction. + + """ + raise NotImplementedError @property def curvature(self): + """ + A positive semi-definite operator or function describing the curvature + of the potential at the given `position`. + + """ + raise NotImplementedError diff --git a/nifty/energies/line_energy.py b/nifty/energies/line_energy.py index 408a69cd..27f09399 100644 --- a/nifty/energies/line_energy.py +++ b/nifty/energies/line_energy.py @@ -20,52 +20,58 @@ from .energy import Energy class LineEnergy(Energy): - """A Energy object restricting an underlying Energy along only some line direction. - Given some Energy and line direction, its position is parametrized by a scalar - step size along the descent direction. + """ Evaluates an underlying Energy along a certain line direction. + + Given an Energy class and a line direction, its position is parametrized by + a scalar step size along the descent direction relative to a zero point. Parameters ---------- position : float The step length parameter along the given line direction. energy : Energy - The Energy object which will be restricted along the given line direction - line_direction : Field, float - Line direction restricting the Energy. - zero_point : Field, float - Fixing the zero point of the line restriction. Used to memorize this position in new - initializations (default : None) + The Energy object which will be evaluated along the given direction. + line_direction : Field + Direction used for line evaluation. + zero_point : Field *optional* + Fixing the zero point of the line restriction. Used to memorize this + position in new initializations. By the default the current position + of the supplied `energy` instance is used (default : None). Attributes ---------- - position : float - The step length along the given line direction. + position : float + The position along the given line direction relative to the zero point. value : float - The evaluation of the energy functional at given position. + The value of the energy functional at given `position`. gradient : float - The gradient along the line direction projected on the current line position. + The gradient of the underlying energy instance along the line direction + projected on the line direction. curvature : callable - A positive semi-definite operator or function describing the curvature of the potential - at given position. + A positive semi-definite operator or function describing the curvature + of the potential at given `position`. line_direction : Field - Direction along which the movement is restricted. Does not have to be normalized. + Direction along which the movement is restricted. Does not have to be + normalized. energy : Energy - The underlying Energy at the resulting position along the line according to the step length. + The underlying Energy at the `position` along the line direction. Raises ------ NotImplementedError Raised if - * value, gradient or curvature of the attribute energy is not implemented. + * value, gradient or curvature of the attribute energy are not + implemented. Notes ----- - The LineEnergy is used in minimization schemes in order to determine the step size along - some descent direction using a line search. It describes an underlying Energy which is restricted - along one direction, only requiring the step size parameter to determine a new position. - + The LineEnergy is used in minimization schemes in order perform line + searches. It describes an underlying Energy which is restricted along one + direction, only requiring the step size parameter to determine a new + position. """ + def __init__(self, position, energy, line_direction, zero_point=None): super(LineEnergy, self).__init__(position=position) self.line_direction = line_direction @@ -78,19 +84,20 @@ class LineEnergy(Energy): self.energy = energy.at(position=position_on_line) def at(self, position): - """ Initializes and returns new LineEnergy object at new position, memorizing the zero point. + """ Returns LineEnergy at new position, memorizing the zero point. Parameters ---------- position : float - Parameter for the new position. + Parameter for the new position on the line direction. Returns ------- out : LineEnergy - LineEnergy object at new position with same zero point. + LineEnergy object at new position with same zero point as `self`. """ + return self.__class__(position, self.energy, self.line_direction, diff --git a/nifty/minimization/.DS_Store b/nifty/minimization/.DS_Store deleted file mode 100644 index f66870e1152c97241fa7e3f01e25c5e9ebb4ef7d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeHK%Sr=55Ukc50)ph|ael!+7()Dld_WYHD1;Rvdft=Y<)@|kffzP|7cWu`-8IwO zHN)0ndmDf)-yW`k1%Nr-5g#6==Fi4(kdoOK%k*FvIq<|FoQoz3tjqcbB$He$_ zFvJKzoG~57b<7gP<_Tgi921$LSyG8fwHh%j>CCsP>xE-t(qT1xSlw(jp;+9`^IMd| zdZMBfkOIdFoac7o{r`sk!~B0t(oPCUfq$id%~tExlCM;~b@FoFYa9KR?lqruH?D)i m5bc;4?U);H$5&C5b