Coverage for mlos_core/mlos_core/optimizers/__init__.py: 97%
29 statements
« prev ^ index » next coverage.py v7.8.0, created at 2025-04-01 00:52 +0000
1#
2# Copyright (c) Microsoft Corporation.
3# Licensed under the MIT License.
4#
5"""
6Initializer module for the mlos_core optimizers.
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.
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.
17This module also provides a simple :py:class:`~.OptimizerFactory` class to
18:py:meth:`~.OptimizerFactory.create` an Optimizer.
20Generally speaking, the :py:mod:`mlos_core` package is intended to be used in
21conjunction with the :py:mod:`mlos_bench` package, which provides a higher-level
22interface for running benchmarks and autotuning experiments.
24See Also
25--------
26mlos_bench.optimizers.mlos_core_optimizer :
27 The mlos_bench Optimizer class that uses the mlos_core Optimizers to run
28 autotuning experiments.
30Notes
31-----
32See `mlos_core/optimizers/README.md
33<https://github.com/microsoft/MLOS/tree/main/mlos_core/mlos_core/optimizers/>`_
34for additional documentation and examples in the source tree.
35"""
37from enum import Enum
39import ConfigSpace
41from mlos_core.optimizers.bayesian_optimizers.smac_optimizer import SmacOptimizer
42from mlos_core.optimizers.flaml_optimizer import FlamlOptimizer
43from mlos_core.optimizers.optimizer import BaseOptimizer
44from mlos_core.optimizers.random_optimizer import RandomOptimizer
45from mlos_core.spaces.adapters import SpaceAdapterFactory, SpaceAdapterType
47__all__ = [
48 "OptimizerType",
49 "ConcreteOptimizer",
50 "SpaceAdapterType",
51 "OptimizerFactory",
52 "BaseOptimizer",
53 "RandomOptimizer",
54 "FlamlOptimizer",
55 "SmacOptimizer",
56]
59class OptimizerType(Enum):
60 """Enumerate supported mlos_core optimizers."""
62 RANDOM = RandomOptimizer
63 """An instance of :class:`~mlos_core.optimizers.random_optimizer.RandomOptimizer`
64 class will be used.
65 """
67 FLAML = FlamlOptimizer
68 """An instance of :class:`~mlos_core.optimizers.flaml_optimizer.FlamlOptimizer`
69 class will be used.
70 """
72 SMAC = SmacOptimizer
73 """An instance of
74 :class:`~mlos_core.optimizers.bayesian_optimizers.smac_optimizer.SmacOptimizer`
75 class will be used.
76 """
79ConcreteOptimizer = RandomOptimizer | FlamlOptimizer | SmacOptimizer
80"""
81Type alias for concrete optimizer classes.
83(e.g., :class:`~mlos_core.optimizers.bayesian_optimizers.smac_optimizer.SmacOptimizer`, etc.)
84"""
86DEFAULT_OPTIMIZER_TYPE = OptimizerType.FLAML
87"""Default optimizer type to use if none is specified."""
90class OptimizerFactory:
91 """Simple factory class for creating
92 :class:`~mlos_core.optimizers.optimizer.BaseOptimizer`-derived objects.
93 """
95 # pylint: disable=too-few-public-methods
97 @staticmethod
98 def create( # pylint: disable=too-many-arguments
99 *,
100 parameter_space: ConfigSpace.ConfigurationSpace,
101 optimization_targets: list[str],
102 optimizer_type: OptimizerType = DEFAULT_OPTIMIZER_TYPE,
103 optimizer_kwargs: dict | None = None,
104 space_adapter_type: SpaceAdapterType = SpaceAdapterType.IDENTITY,
105 space_adapter_kwargs: dict | None = None,
106 ) -> ConcreteOptimizer:
107 """
108 Create a new optimizer instance, given the parameter space, optimizer type, and
109 potential optimizer options.
111 Parameters
112 ----------
113 parameter_space : ConfigSpace.ConfigurationSpace
114 Input configuration space.
115 optimization_targets : list[str]
116 The names of the optimization targets to minimize.
117 optimizer_type : OptimizerType
118 Optimizer class as defined by Enum.
119 optimizer_kwargs : dict | None
120 Optional arguments passed in Optimizer class constructor.
121 space_adapter_type : SpaceAdapterType | None
122 Space adapter class to be used alongside the optimizer.
123 space_adapter_kwargs : dict | None
124 Optional arguments passed in SpaceAdapter class constructor.
126 Returns
127 -------
128 optimizer : ConcreteOptimizer
129 Instance of concrete optimizer class
130 (e.g., RandomOptimizer, FlamlOptimizer, SmacOptimizer, etc.).
131 """
132 if space_adapter_kwargs is None:
133 space_adapter_kwargs = {}
134 if optimizer_kwargs is None:
135 optimizer_kwargs = {}
137 space_adapter = SpaceAdapterFactory.create(
138 parameter_space=parameter_space,
139 space_adapter_type=space_adapter_type,
140 space_adapter_kwargs=space_adapter_kwargs,
141 )
143 optimizer: ConcreteOptimizer = optimizer_type.value(
144 parameter_space=parameter_space,
145 optimization_targets=optimization_targets,
146 space_adapter=space_adapter,
147 **optimizer_kwargs,
148 )
150 return optimizer