iteration_controller.py 2.79 KB
Newer Older
Martin Reinecke's avatar
Martin Reinecke committed
1
2
3
4
5
6
7
8
9
10
11
12
13
# 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/>.
#
Martin Reinecke's avatar
Martin Reinecke committed
14
# Copyright(C) 2013-2018 Max-Planck-Society
Martin Reinecke's avatar
Martin Reinecke committed
15
16
17
18
#
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
# and financially supported by the Studienstiftung des deutschen Volkes.

19
from __future__ import absolute_import, division, print_function
20

Martin Reinecke's avatar
Martin Reinecke committed
21
import abc
22
23

from ..compat import *
Martin Reinecke's avatar
Martin Reinecke committed
24
from ..utilities import NiftyMetaBase
Martin Reinecke's avatar
Martin Reinecke committed
25

Martin Reinecke's avatar
Martin Reinecke committed
26

Martin Reinecke's avatar
Martin Reinecke committed
27
class IterationController(NiftyMetaBase()):
Martin Reinecke's avatar
Martin Reinecke committed
28
29
30
31
32
33
34
35
36
37
38
39
40
    """The abstract base class for all iteration controllers.
    An iteration controller is an object that monitors the progress of a
    minimization iteration. At the begin of the minimization, its start()
    method is called with the energy object at the initial position.
    Afterwards, its check() method is called during every iteration step with
    the energy object describing the current position.
    Based on that information, the iteration controller has to decide whether
    iteration needs to progress further (in this case it returns CONTINUE), or
    if sufficient convergence has been reached (in this case it returns
    CONVERGED), or if some error has been detected (then it returns ERROR).

    The concrete convergence criteria can be chosen by inheriting from this
    class; the implementer has full flexibility to use whichever criteria are
Martin Reinecke's avatar
tweaks  
Martin Reinecke committed
41
    appropriate for a particular problem - as long as they can be computed from
Martin Reinecke's avatar
Martin Reinecke committed
42
43
    the information passed to the controller during the iteration process.
    """
Martin Reinecke's avatar
Martin Reinecke committed
44

Martin Reinecke's avatar
Martin Reinecke committed
45
    CONVERGED, CONTINUE, ERROR = list(range(3))
Martin Reinecke's avatar
Martin Reinecke committed
46
47
48

    @abc.abstractmethod
    def start(self, energy):
Martin Reinecke's avatar
Martin Reinecke committed
49
50
        """Starts the iteration.

Martin Reinecke's avatar
Martin Reinecke committed
51
52
53
54
55
56
57
58
59
60
61
62
63
        Parameters
        ----------
        energy : Energy object
           Energy object at the start of the iteration

        Returns
        -------
        status : integer status, can be CONVERGED, CONTINUE or ERROR
        """
        raise NotImplementedError

    @abc.abstractmethod
    def check(self, energy):
Martin Reinecke's avatar
Martin Reinecke committed
64
65
        """Checks the state of the iteration. Called after every step.

Martin Reinecke's avatar
Martin Reinecke committed
66
67
68
69
70
71
72
73
74
75
        Parameters
        ----------
        energy : Energy object
           Energy object at the start of the iteration

        Returns
        -------
        status : integer status, can be CONVERGED, CONTINUE or ERROR
        """
        raise NotImplementedError