energy.py 3.96 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
14
15
16
17
#
# Copyright(C) 2013-2017 Max-Planck-Society
#
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
# and financially supported by the Studienstiftung des deutschen Volkes.
18

19
from ..nifty_meta import NiftyMeta
20
from .memoization import memo
21

22
from keepers import Loggable
Martin Reinecke's avatar
Martin Reinecke committed
23
from future.utils import with_metaclass
24

25

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

29
30
   The Energy object is an implementation of a scalar function including its
   gradient and curvature at some position.
31
32
33

    Parameters
    ----------
34
35
    position : Field
        The input parameter of the scalar function.
36
37
38

    Attributes
    ----------
39
40
41
42
43
44
    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
Martin Reinecke's avatar
Martin Reinecke committed
45
        The gradient at given `position`.
46
47
48
    curvature : LinearOperator, callable
        A positive semi-definite operator or function describing the curvature
        of the potential at the given `position`.
49
50
51

    Notes
    -----
52
53
54
55
56
57
    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.
58

59
60
61
62
63
64
    Memorizing the evaluations of some quantities (using the memo decorator)
    minimizes the computational effort for multiple calls.

    See also
    --------
    memo
65
66

    """
67

68
    def __init__(self, position):
69
        super(Energy, self).__init__()
70
        self._cache = {}
71
        self._position = position.copy()
72
73

    def at(self, position):
74
        """ Initializes and returns a new Energy object at the new position.
75
76
77
78
79
80
81
82
83
84
85
86

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

        Returns
        -------
        out : Energy
            Energy object at new position.

        """
87

88
89
        return self.__class__(position)

90
91
    @property
    def position(self):
92
93
94
95
96
97
        """
        The Field location in parameter space where value, gradient and
        curvature are evaluated.

        """

98
99
        return self._position

100
101
    @property
    def value(self):
102
103
104
105
106
        """
        The value of the energy functional at given `position`.

        """

107
108
109
110
        raise NotImplementedError

    @property
    def gradient(self):
111
        """
Martin Reinecke's avatar
Martin Reinecke committed
112
        The gradient at given `position`.
113
114
115

        """

116
117
        raise NotImplementedError

Martin Reinecke's avatar
Martin Reinecke committed
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
    @property
    @memo
    def gradient_norm(self):
        """
        The length of the gradient at given `position`.

        """

        return self.gradient.norm()

    @property
    @memo
    def gradient_infnorm(self):
        """
        The infinity norm of the gradient at given `position`.

        """

        return abs(self.gradient).max()

138
139
    @property
    def curvature(self):
140
141
142
143
144
145
        """
        A positive semi-definite operator or function describing the curvature
        of the potential at the given `position`.

        """

146
        raise NotImplementedError