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 

32 

33import ConfigSpace 

34 

35from mlos_core.optimizers.bayesian_optimizers.smac_optimizer import SmacOptimizer 

36from mlos_core.optimizers.flaml_optimizer import FlamlOptimizer 

37from mlos_core.optimizers.optimizer import BaseOptimizer 

38from mlos_core.optimizers.random_optimizer import RandomOptimizer 

39from mlos_core.spaces.adapters import SpaceAdapterFactory, SpaceAdapterType 

40 

41__all__ = [ 

42 "OptimizerType", 

43 "ConcreteOptimizer", 

44 "SpaceAdapterType", 

45 "OptimizerFactory", 

46 "BaseOptimizer", 

47 "RandomOptimizer", 

48 "FlamlOptimizer", 

49 "SmacOptimizer", 

50] 

51 

52 

53class OptimizerType(Enum): 

54 """Enumerate supported mlos_core optimizers.""" 

55 

56 RANDOM = RandomOptimizer 

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

58 class will be used. 

59 """ 

60 

61 FLAML = FlamlOptimizer 

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

63 class will be used. 

64 """ 

65 

66 SMAC = SmacOptimizer 

67 """An instance of 

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

69 class will be used. 

70 """ 

71 

72 

73ConcreteOptimizer = RandomOptimizer | FlamlOptimizer | SmacOptimizer 

74""" 

75Type alias for concrete optimizer classes. 

76 

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

78""" 

79 

80DEFAULT_OPTIMIZER_TYPE = OptimizerType.FLAML 

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

82 

83 

84class OptimizerFactory: 

85 """Simple factory class for creating 

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

87 """ 

88 

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

90 

91 @staticmethod 

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

93 *, 

94 parameter_space: ConfigSpace.ConfigurationSpace, 

95 optimization_targets: list[str], 

96 optimizer_type: OptimizerType = DEFAULT_OPTIMIZER_TYPE, 

97 optimizer_kwargs: dict | None = None, 

98 space_adapter_type: SpaceAdapterType = SpaceAdapterType.IDENTITY, 

99 space_adapter_kwargs: dict | None = None, 

100 ) -> ConcreteOptimizer: 

101 """ 

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

103 potential optimizer options. 

104 

105 Parameters 

106 ---------- 

107 parameter_space : ConfigSpace.ConfigurationSpace 

108 Input configuration space. 

109 optimization_targets : list[str] 

110 The names of the optimization targets to minimize. 

111 optimizer_type : OptimizerType 

112 Optimizer class as defined by Enum. 

113 optimizer_kwargs : dict | None 

114 Optional arguments passed in Optimizer class constructor. 

115 space_adapter_type : SpaceAdapterType | None 

116 Space adapter class to be used alongside the optimizer. 

117 space_adapter_kwargs : dict | None 

118 Optional arguments passed in SpaceAdapter class constructor. 

119 

120 Returns 

121 ------- 

122 optimizer : ConcreteOptimizer 

123 Instance of concrete optimizer class 

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

125 """ 

126 if space_adapter_kwargs is None: 

127 space_adapter_kwargs = {} 

128 if optimizer_kwargs is None: 

129 optimizer_kwargs = {} 

130 

131 space_adapter = SpaceAdapterFactory.create( 

132 parameter_space=parameter_space, 

133 space_adapter_type=space_adapter_type, 

134 space_adapter_kwargs=space_adapter_kwargs, 

135 ) 

136 

137 optimizer: ConcreteOptimizer = optimizer_type.value( 

138 parameter_space=parameter_space, 

139 optimization_targets=optimization_targets, 

140 space_adapter=space_adapter, 

141 **optimizer_kwargs, 

142 ) 

143 

144 return optimizer