Coverage for mlos_core/mlos_core/optimizers/__init__.py: 97%

1# 

2# Copyright (c) Microsoft Corporation. 

3# Licensed under the MIT License. 

4# 

5""" 

6Initializer module for the mlos_core optimizers. 

7 

8Optimizers are the main component of the :py:mod:`mlos_core` package. 

9They act as a wrapper around other OSS tuning libraries to provide a consistent API 

10interface to allow experimenting with different autotuning algorithms. 

11 

12The :class:`~mlos_core.optimizers.optimizer.BaseOptimizer` class is the base class 

13for all Optimizers and provides the core 

14:py:meth:`~mlos_core.optimizers.optimizer.BaseOptimizer.suggest` and 

15:py:meth:`~mlos_core.optimizers.optimizer.BaseOptimizer.register` methods. 

16 

17This module also provides a simple :py:class:`~.OptimizerFactory` class to 

18:py:meth:`~.OptimizerFactory.create` an Optimizer. 

19 

20Examples 

21-------- 

22TODO: Add example usage here. 

23 

24Notes 

25----- 

26See `mlos_core/optimizers/README.md 

27<https://github.com/microsoft/MLOS/tree/main/mlos_core/mlos_core/optimizers/>`_ 

28for additional documentation and examples in the source tree. 

29""" 

30 

31from enum import Enum 

32from typing import List, Optional, TypeVar 

33 

34import ConfigSpace 

35 

36from mlos_core.optimizers.bayesian_optimizers.smac_optimizer import SmacOptimizer 

37from mlos_core.optimizers.flaml_optimizer import FlamlOptimizer 

38from mlos_core.optimizers.optimizer import BaseOptimizer 

39from mlos_core.optimizers.random_optimizer import RandomOptimizer 

40from mlos_core.spaces.adapters import SpaceAdapterFactory, SpaceAdapterType 

41 

42__all__ = [ 

43 "OptimizerType", 

44 "ConcreteOptimizer", 

45 "SpaceAdapterType", 

46 "OptimizerFactory", 

47 "BaseOptimizer", 

48 "RandomOptimizer", 

49 "FlamlOptimizer", 

50 "SmacOptimizer", 

51] 

52 

53 

54class OptimizerType(Enum): 

55 """Enumerate supported mlos_core optimizers.""" 

56 

57 RANDOM = RandomOptimizer 

58 """An instance of :class:`~mlos_core.optimizers.random_optimizer.RandomOptimizer` 

59 class will be used. 

60 """ 

61 

62 FLAML = FlamlOptimizer 

63 """An instance of :class:`~mlos_core.optimizers.flaml_optimizer.FlamlOptimizer` 

64 class will be used. 

65 """ 

66 

67 SMAC = SmacOptimizer 

68 """An instance of 

69 :class:`~mlos_core.optimizers.bayesian_optimizers.smac_optimizer.SmacOptimizer` 

70 class will be used. 

71 """ 

72 

73 

74# To make mypy happy, we need to define a type variable for each optimizer type. 

75# https://github.com/python/mypy/issues/12952 

76# ConcreteOptimizer = TypeVar('ConcreteOptimizer', *[member.value for member in OptimizerType]) 

77# To address this, we add a test for complete coverage of the enum. 

78 

79ConcreteOptimizer = TypeVar( 

80 "ConcreteOptimizer", 

81 RandomOptimizer, 

82 FlamlOptimizer, 

83 SmacOptimizer, 

84) 

85""" 

86Type variable for concrete optimizer classes. 

87 

88(e.g., :class:`~mlos_core.optimizers.bayesian_optimizers.smac_optimizer.SmacOptimizer`, etc.) 

89""" 

90 

91DEFAULT_OPTIMIZER_TYPE = OptimizerType.FLAML 

92"""Default optimizer type to use if none is specified.""" 

93 

94 

95class OptimizerFactory: 

96 """Simple factory class for creating 

97 :class:`~mlos_core.optimizers.optimizer.BaseOptimizer`-derived objects. 

98 """ 

99 

100 # pylint: disable=too-few-public-methods 

101 

102 @staticmethod 

103 def create( # pylint: disable=too-many-arguments 

104 *, 

105 parameter_space: ConfigSpace.ConfigurationSpace, 

106 optimization_targets: List[str], 

107 optimizer_type: OptimizerType = DEFAULT_OPTIMIZER_TYPE, 

108 optimizer_kwargs: Optional[dict] = None, 

109 space_adapter_type: SpaceAdapterType = SpaceAdapterType.IDENTITY, 

110 space_adapter_kwargs: Optional[dict] = None, 

111 ) -> ConcreteOptimizer: # type: ignore[type-var] 

112 """ 

113 Create a new optimizer instance, given the parameter space, optimizer type, and 

114 potential optimizer options. 

115 

116 Parameters 

117 ---------- 

118 parameter_space : ConfigSpace.ConfigurationSpace 

119 Input configuration space. 

120 optimization_targets : List[str] 

121 The names of the optimization targets to minimize. 

122 optimizer_type : OptimizerType 

123 Optimizer class as defined by Enum. 

124 optimizer_kwargs : Optional[dict] 

125 Optional arguments passed in Optimizer class constructor. 

126 space_adapter_type : Optional[SpaceAdapterType] 

127 Space adapter class to be used alongside the optimizer. 

128 space_adapter_kwargs : Optional[dict] 

129 Optional arguments passed in SpaceAdapter class constructor. 

130 

131 Returns 

132 ------- 

133 optimizer : ConcreteOptimizer 

134 Instance of concrete optimizer class 

135 (e.g., RandomOptimizer, FlamlOptimizer, SmacOptimizer, etc.). 

136 """ 

137 if space_adapter_kwargs is None: 

138 space_adapter_kwargs = {} 

139 if optimizer_kwargs is None: 

140 optimizer_kwargs = {} 

141 

142 space_adapter = SpaceAdapterFactory.create( 

143 parameter_space=parameter_space, 

144 space_adapter_type=space_adapter_type, 

145 space_adapter_kwargs=space_adapter_kwargs, 

146 ) 

147 

148 optimizer: ConcreteOptimizer = optimizer_type.value( 

149 parameter_space=parameter_space, 

150 optimization_targets=optimization_targets, 

151 space_adapter=space_adapter, 

152 **optimizer_kwargs, 

153 ) 

154 

155 return optimizer