0
# Optimization Facades
1

2
High-level interfaces that pre-configure SMAC components for specific optimization scenarios. Each facade extends `AbstractFacade` and provides static methods for customizing individual components while maintaining sensible defaults.
3

4
## Capabilities
5

6
### Abstract Base Facade
7

8
Base class providing the core optimization interface used by all concrete facades.
9

10
```python { .api }
11
class AbstractFacade:
12
    def __init__(
13
        self,
14
        scenario: Scenario,
15
        target_function: Callable | str | AbstractRunner,
16
        *,
17
        model: AbstractModel | None = None,
18
        acquisition_function: AbstractAcquisitionFunction | None = None,
19
        acquisition_maximizer: AbstractAcquisitionMaximizer | None = None,
20
        initial_design: AbstractInitialDesign | None = None,
21
        random_design: AbstractRandomDesign | None = None,
22
        intensifier: AbstractIntensifier | None = None,
23
        multi_objective_algorithm: AbstractMultiObjectiveAlgorithm | None = None,
24
        runhistory_encoder: AbstractRunHistoryEncoder | None = None,
25
        config_selector: ConfigSelector | None = None,
26
        logging_level: int | Path | Literal[False] | None = None,
27
        callbacks: list[Callback] = None,
28
        overwrite: bool = False,
29
        dask_client: Client | None = None
30
    ): ...
31
    
32
    def ask(self) -> TrialInfo:
33
        """Get next configuration to evaluate."""
34
    
35
    def tell(self, info: TrialInfo, value: TrialValue, save: bool = True) -> None:
36
        """Report trial results."""
37
    
38
    def optimize(self, *, data_to_scatter: dict[str, Any] | None = None) -> Configuration | list[Configuration]:
39
        """Run optimization loop."""
40
    
41
    def validate(self, config: Configuration, *, seed: int | None = None) -> float | list[float]:
42
        """Validate configuration."""
43
    
44
    @property
45
    def scenario(self) -> Scenario: ...
46
    
47
    @property
48
    def runhistory(self) -> RunHistory: ...
49
    
50
    @property
51
    def optimizer(self) -> SMBO: ...
52
    
53
    @property
54
    def intensifier(self) -> AbstractIntensifier: ...
55
    
56
    @property
57
    def meta(self) -> dict[str, Any]: ...
58
```
59

60
### BlackBox Optimization
61

62
General-purpose Bayesian optimization using Gaussian processes, ideal for continuous optimization problems without categorical hyperparameters.
63

64
```python { .api }
65
class BlackBoxFacade(AbstractFacade):
66
    @staticmethod
67
    def get_model(scenario, *, model_type="vanilla", kernel=None) -> AbstractGaussianProcess:
68
        """Configure Gaussian process model."""
69
    
70
    @staticmethod
71
    def get_kernel(scenario) -> kernels.Kernel:
72
        """Get composite kernel for Gaussian process."""
73
    
74
    @staticmethod
75
    def get_acquisition_function(scenario, *, xi=0.0) -> EI:
76
        """Configure Expected Improvement acquisition function."""
77
    
78
    @staticmethod
79
    def get_acquisition_maximizer(scenario, *, challengers=1000, local_search_iterations=10) -> LocalAndSortedRandomSearch:
80
        """Configure acquisition optimizer."""
81
    
82
    @staticmethod
83
    def get_intensifier(scenario, *, max_config_calls=3, max_incumbents=20) -> Intensifier:
84
        """Configure trial intensifier."""
85
    
86
    @staticmethod
87
    def get_initial_design(scenario, *, n_configs=None, n_configs_per_hyperparamter=8, max_ratio=0.25, additional_configs=None) -> SobolInitialDesign:
88
        """Configure Sobol sequence initial design."""
89
    
90
    @staticmethod
91
    def get_random_design(scenario, *, probability=0.08447232371720552) -> ProbabilityRandomDesign:
92
        """Configure random exploration."""
93
    
94
    @staticmethod
95
    def get_multi_objective_algorithm(scenario, *, objective_weights=None) -> MeanAggregationStrategy:
96
        """Configure multi-objective handling."""
97
    
98
    @staticmethod
99
    def get_runhistory_encoder(scenario) -> RunHistoryEncoder:
100
        """Configure feature encoding."""
101
    
102
    @staticmethod
103
    def get_config_selector(scenario, *, retrain_after=1, retries=16) -> ConfigSelector:
104
        """Configure model retraining schedule."""
105
```
106

107
Usage example:
108

109
```python
110
from smac import BlackBoxFacade, Scenario
111
from ConfigSpace import ConfigurationSpace, Float
112

113
def objective(config):
114
    return config["x"]**2 + config["y"]**2
115

116
config_space = ConfigurationSpace()
117
config_space.add_hyperparameter(Float("x", bounds=(-5.0, 5.0)))
118
config_space.add_hyperparameter(Float("y", bounds=(-5.0, 5.0)))
119

120
scenario = Scenario(configspace=config_space, n_trials=100)
121
facade = BlackBoxFacade(scenario, objective)
122
incumbent = facade.optimize()
123
```
124

125
### Hyperparameter Optimization
126

127
Hyperparameter optimization using random forests, suitable for mixed continuous/categorical spaces with moderate numbers of hyperparameters.
128

129
```python { .api }
130
class HyperparameterOptimizationFacade(AbstractFacade):
131
    @staticmethod
132
    def get_model(scenario, *, n_trees=10, ratio_features=1.0, min_samples_split=2, min_samples_leaf=1, max_depth=2**20, bootstrapping=True) -> RandomForest:
133
        """Configure random forest surrogate model."""
134
    
135
    @staticmethod
136
    def get_acquisition_function(scenario, *, xi=0.0) -> EI:
137
        """Configure Expected Improvement acquisition function."""
138
    
139
    @staticmethod
140
    def get_acquisition_maximizer(scenario, *, challengers=10000, local_search_iterations=10) -> LocalAndSortedRandomSearch:
141
        """Configure acquisition optimizer with more challengers."""
142
    
143
    @staticmethod
144
    def get_intensifier(scenario, *, max_config_calls=3, max_incumbents=10) -> Intensifier:
145
        """Configure trial intensifier."""
146
    
147
    @staticmethod
148
    def get_initial_design(scenario, *, n_configs=None, n_configs_per_hyperparamter=10, max_ratio=0.25, additional_configs=None) -> SobolInitialDesign:
149
        """Configure Sobol sequence initial design."""
150
    
151
    @staticmethod
152
    def get_random_design(scenario, *, probability=0.2) -> ProbabilityRandomDesign:
153
        """Configure random exploration with higher probability."""
154
    
155
    @staticmethod
156
    def get_multi_objective_algorithm(scenario, *, objective_weights=None) -> MeanAggregationStrategy:
157
        """Configure multi-objective handling."""
158
    
159
    @staticmethod
160
    def get_runhistory_encoder(scenario) -> RunHistoryLogScaledEncoder:
161
        """Configure log-scaled feature encoding."""
162
```
163

164
### Multi-Fidelity Optimization
165

166
Multi-fidelity optimization using Hyperband for efficient budget allocation, extending hyperparameter optimization with successive halving.
167

168
```python { .api }
169
class MultiFidelityFacade(HyperparameterOptimizationFacade):
170
    @staticmethod
171
    def get_intensifier(scenario, *, eta=3, n_seeds=1, instance_seed_order="shuffle_once", max_incumbents=10, incumbent_selection="highest_observed_budget") -> Hyperband:
172
        """Configure Hyperband intensifier with successive halving."""
173
    
174
    @staticmethod
175
    def get_initial_design(scenario, *, n_configs=None, n_configs_per_hyperparamter=10, max_ratio=0.25, additional_configs=None) -> RandomInitialDesign:
176
        """Configure random initial design for multi-fidelity."""
177
```
178

179
Usage requires scenario with budget configuration:
180

181
```python
182
from smac import MultiFidelityFacade, Scenario
183

184
def multi_fidelity_objective(config, seed=0, budget=1.0):
185
    # Use budget to control evaluation fidelity
186
    return expensive_evaluation(config, fidelity=budget)
187

188
scenario = Scenario(
189
    configspace=config_space,
190
    n_trials=50,
191
    min_budget=0.1,  # Required for multi-fidelity
192
    max_budget=1.0   # Required for multi-fidelity
193
)
194

195
facade = MultiFidelityFacade(scenario, multi_fidelity_objective)
196
```
197

198
### Algorithm Configuration
199

200
Algorithm configuration for tuning algorithm parameters across multiple problem instances with intensive evaluation.
201

202
```python { .api }
203
class AlgorithmConfigurationFacade(AbstractFacade):
204
    @staticmethod
205
    def get_model(scenario, *, n_trees=10, ratio_features=5.0/6.0, min_samples_split=3, min_samples_leaf=3, max_depth=20, bootstrapping=True, pca_components=4) -> RandomForest:
206
        """Configure random forest with PCA dimensionality reduction."""
207
    
208
    @staticmethod
209
    def get_acquisition_function(scenario, *, xi=0.0) -> EI:
210
        """Configure Expected Improvement acquisition function."""
211
    
212
    @staticmethod
213
    def get_acquisition_maximizer(scenario) -> LocalAndSortedRandomSearch:
214
        """Configure acquisition optimizer."""
215
    
216
    @staticmethod
217
    def get_intensifier(scenario, *, max_config_calls=2000, max_incumbents=10) -> Intensifier:
218
        """Configure intensive trial evaluation."""
219
    
220
    @staticmethod
221
    def get_initial_design(scenario, *, additional_configs=None) -> DefaultInitialDesign:
222
        """Configure default-only initial design."""
223
    
224
    @staticmethod
225
    def get_random_design(scenario, *, probability=0.5) -> ProbabilityRandomDesign:
226
        """Configure high random exploration."""
227
    
228
    @staticmethod
229
    def get_multi_objective_algorithm(scenario, *, objective_weights=None) -> MeanAggregationStrategy:
230
        """Configure multi-objective handling."""
231
    
232
    @staticmethod
233
    def get_runhistory_encoder(scenario) -> RunHistoryEncoder:
234
        """Configure standard feature encoding."""
235
```
236

237
### Random Search Baseline
238

239
Random Online Aggressive Racing (ROAR) baseline using pure random search without surrogate models.
240

241
```python { .api }
242
class RandomFacade(AbstractFacade):
243
    @staticmethod
244
    def get_model(scenario) -> RandomModel:
245
        """Get dummy random model."""
246
    
247
    @staticmethod
248
    def get_acquisition_function(scenario) -> AbstractAcquisitionFunction:
249
        """Get dummy acquisition function."""
250
    
251
    @staticmethod
252
    def get_acquisition_maximizer(scenario) -> RandomSearch:
253
        """Configure pure random search."""
254
    
255
    @staticmethod
256
    def get_intensifier(scenario, *, max_config_calls=3, max_incumbents=10) -> Intensifier:
257
        """Configure trial intensifier."""
258
    
259
    @staticmethod
260
    def get_initial_design(scenario, *, additional_configs=None) -> DefaultInitialDesign:
261
        """Configure default-only initial design."""
262
    
263
    @staticmethod
264
    def get_random_design(scenario) -> AbstractRandomDesign:
265
        """Get dummy random design."""
266
    
267
    @staticmethod
268
    def get_multi_objective_algorithm(scenario, *, objective_weights=None) -> MeanAggregationStrategy:
269
        """Configure multi-objective handling."""
270
    
271
    @staticmethod
272
    def get_runhistory_encoder(scenario) -> RunHistoryEncoder:
273
        """Configure standard feature encoding."""
274
```
275

276
### Model-Free Hyperband
277

278
Model-free Hyperband algorithm for multi-fidelity optimization without surrogate models, combining random search with successive halving.
279

280
```python { .api }
281
class HyperbandFacade(RandomFacade):
282
    @staticmethod
283
    def get_intensifier(scenario, *, eta=3, n_seeds=1, instance_seed_order="shuffle_once", max_incumbents=10, incumbent_selection="highest_observed_budget") -> Hyperband:
284
        """Configure Hyperband intensifier with successive halving."""
285
```