energy.py 3.29 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
Theo Steininger's avatar
Theo Steininger committed
13
#
Martin Reinecke's avatar
Martin Reinecke committed
14
# Copyright(C) 2013-2018 Max-Planck-Society
Theo Steininger's avatar
Theo Steininger committed
15 16 17
#
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
# and financially supported by the Studienstiftung des deutschen Volkes.
18

Martin Reinecke's avatar
Martin Reinecke committed
19
from ..utilities import memo, NiftyMeta
Martin Reinecke's avatar
Martin Reinecke committed
20
from future.utils import with_metaclass
21

22

Martin Reinecke's avatar
Martin Reinecke committed
23
class Energy(with_metaclass(NiftyMeta, type('NewBase', (object,), {}))):
24
    """ Provides the functional used by minimization schemes.
25

26 27
   The Energy object is an implementation of a scalar function including its
   gradient and curvature at some position.
28 29 30

    Parameters
    ----------
31 32
    position : Field
        The input parameter of the scalar function.
33 34 35

    Notes
    -----
36 37 38 39 40 41
    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.
42

43 44 45
    Memorizing the evaluations of some quantities (using the memo decorator)
    minimizes the computational effort for multiple calls.

Martin Reinecke's avatar
Martin Reinecke committed
46
    See Also
47 48
    --------
    memo
49 50

    """
51

52
    def __init__(self, position):
53
        super(Energy, self).__init__()
Martin Reinecke's avatar
Martin Reinecke committed
54
        self._position = position.lock()
55 56

    def at(self, position):
57
        """ Initializes and returns a new Energy object at the new position.
58 59 60 61 62 63 64 65

        Parameters
        ----------
        position : Field
            Parameter for the new Energy object.

        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
66
        Energy
67 68
            Energy object at new position.
        """
69 70
        return self.__class__(position)

71 72
    @property
    def position(self):
73 74 75 76
        """
        The Field location in parameter space where value, gradient and
        curvature are evaluated.
        """
77 78
        return self._position

79 80
    @property
    def value(self):
81
        """
Martin Reinecke's avatar
Martin Reinecke committed
82 83
        float
            The value of the energy functional at given `position`.
84
        """
85 86 87 88
        raise NotImplementedError

    @property
    def gradient(self):
89
        """
Martin Reinecke's avatar
Martin Reinecke committed
90 91
        Field
            The gradient at given `position`.
92
        """
93 94
        raise NotImplementedError

Martin Reinecke's avatar
Martin Reinecke committed
95 96 97 98
    @property
    @memo
    def gradient_norm(self):
        """
Martin Reinecke's avatar
Martin Reinecke committed
99 100
        float
            The length of the gradient at given `position`.
Martin Reinecke's avatar
Martin Reinecke committed
101 102 103
        """
        return self.gradient.norm()

104 105
    @property
    def curvature(self):
106
        """
Martin Reinecke's avatar
Martin Reinecke committed
107 108 109
        LinearOperator
            A positive semi-definite operator or function describing the
            curvature of the potential at the given `position`.
110
        """
111
        raise NotImplementedError