tuner.py 5.06 KB
Newer Older
Deshui Yu's avatar
Deshui Yu committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Copyright (c) Microsoft Corporation. All rights reserved.
#
# MIT License
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
# associated documentation files (the "Software"), to deal in the Software without restriction,
# including without limitation the rights to use, copy, modify, merge, publish, distribute,
# sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all copies or
# substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
# NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
# OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# ==================================================================================================
import logging

xuehui's avatar
xuehui committed
22
import nni
23

24
from .recoverable import Recoverable
Deshui Yu's avatar
Deshui Yu committed
25
26
27
28

_logger = logging.getLogger(__name__)


29
class Tuner(Recoverable):
Deshui Yu's avatar
Deshui Yu committed
30
31
    # pylint: disable=no-self-use,unused-argument

32
    def generate_parameters(self, parameter_id, **kwargs):
Deshui Yu's avatar
Deshui Yu committed
33
34
35
36
37
38
        """Returns a set of trial (hyper-)parameters, as a serializable object.
        User code must override either this function or 'generate_multiple_parameters()'.
        parameter_id: int
        """
        raise NotImplementedError('Tuner: generate_parameters not implemented')

39
    def generate_multiple_parameters(self, parameter_id_list, **kwargs):
Deshui Yu's avatar
Deshui Yu committed
40
41
42
        """Returns multiple sets of trial (hyper-)parameters, as iterable of serializable objects.
        Call 'generate_parameters()' by 'count' times by default.
        User code must override either this function or 'generate_parameters()'.
43
44
        If there's no more trial, user should raise nni.NoMoreTrialError exception in generate_parameters().
        If so, this function will only return sets of trial (hyper-)parameters that have already been collected.
Deshui Yu's avatar
Deshui Yu committed
45
46
        parameter_id_list: list of int
        """
xuehui's avatar
xuehui committed
47
48
        result = []
        for parameter_id in parameter_id_list:
xuehui's avatar
xuehui committed
49
            try:
Yan Ni's avatar
Yan Ni committed
50
                _logger.debug("generating param for {}".format(parameter_id))
51
                res = self.generate_parameters(parameter_id, **kwargs)
xuehui's avatar
xuehui committed
52
53
54
            except nni.NoMoreTrialError:
                return result
            result.append(res)
xuehui's avatar
xuehui committed
55
        return result
Deshui Yu's avatar
Deshui Yu committed
56

57
    def receive_trial_result(self, parameter_id, parameters, value, **kwargs):
Deshui Yu's avatar
Deshui Yu committed
58
        """Invoked when a trial reports its final result. Must override.
59
60
        By default this only reports results of algorithm-generated hyper-parameters.
        Use `accept_customized_trials()` to receive results from user-added parameters.
Deshui Yu's avatar
Deshui Yu committed
61
62
        parameter_id: int
        parameters: object created by 'generate_parameters()'
63
64
65
        value: object reported by trial
        customized: bool, true if the trial is created from web UI, false if generated by algorithm
        trial_job_id: str, only available in multiphase mode.
Deshui Yu's avatar
Deshui Yu committed
66
67
68
        """
        raise NotImplementedError('Tuner: receive_trial_result not implemented')

69
70
71
72
    def accept_customized_trials(self, accept=True):
        """Enable or disable receiving results of user-added hyper-parameters. 
        By default `receive_trial_result()` will only receive results of algorithm-generated hyper-parameters.
        If tuners want to receive those of customized parameters as well, they can call this function in `__init__()`.
Deshui Yu's avatar
Deshui Yu committed
73
        """
74
        self._accept_customized = accept
Deshui Yu's avatar
Deshui Yu committed
75

76
    def trial_end(self, parameter_id, success, **kwargs):
77
78
79
80
81
82
        """Invoked when a trial is completed or terminated. Do nothing by default.
        parameter_id: int
        success: True if the trial successfully completed; False if failed or terminated
        """
        pass

Deshui Yu's avatar
Deshui Yu committed
83
84
85
86
87
88
    def update_search_space(self, search_space):
        """Update the search space of tuner. Must override.
        search_space: JSON object
        """
        raise NotImplementedError('Tuner: update_search_space not implemented')

89
    def load_checkpoint(self):
Deshui Yu's avatar
Deshui Yu committed
90
91
92
        """Load the checkpoint of tuner.
        path: checkpoint directory for tuner
        """
93
94
        checkpoin_path = self.get_checkpoint_path()
        _logger.info('Load checkpoint ignored by tuner, checkpoint path: %s' % checkpoin_path)
Deshui Yu's avatar
Deshui Yu committed
95

96
    def save_checkpoint(self):
Deshui Yu's avatar
Deshui Yu committed
97
98
99
        """Save the checkpoint of tuner.
        path: checkpoint directory for tuner
        """
100
101
        checkpoin_path = self.get_checkpoint_path()
        _logger.info('Save checkpoint ignored by tuner, checkpoint path: %s' % checkpoin_path)
Deshui Yu's avatar
Deshui Yu committed
102

103
104
105
106
107
108
    def import_data(self, data):
        """Import additional data for tuning
        data: a list of dictionarys, each of which has at least two keys, 'parameter' and 'value'
        """
        pass

109
110
    def _on_exit(self):
        pass
Deshui Yu's avatar
Deshui Yu committed
111

112
113
    def _on_error(self):
        pass