0
# SMAC3
1

2
SMAC3 (Sequential Model-based Algorithm Configuration) is a versatile Bayesian Optimization package for hyperparameter optimization and algorithm configuration. It provides a robust framework for determining well-performing hyperparameter configurations for Machine Learning algorithms, datasets, and applications using Bayesian Optimization combined with aggressive racing mechanisms.
3

4
## Package Information
5

6
- **Package Name**: smac
7
- **Language**: Python
8
- **Installation**: `pip install smac`
9

10
## Core Imports
11

12
```python
13
import smac
14
```
15

16
Common facade imports:
17

18
```python
19
from smac import BlackBoxFacade, HyperparameterOptimizationFacade, MultiFidelityFacade
20
from smac import Scenario, RunHistory, Callback
21
```
22

23
Direct component imports:
24

25
```python
26
from smac.facade import AbstractFacade
27
from smac.scenario import Scenario
28
from smac.runhistory import RunHistory, TrialInfo, TrialValue, StatusType
29
from smac.callback import Callback, MetadataCallback
30
```
31

32
## Basic Usage
33

34
```python
35
from smac import HyperparameterOptimizationFacade, Scenario
36
from ConfigSpace import Configuration, ConfigurationSpace, Float
37

38
# Define configuration space
39
config_space = ConfigurationSpace()
40
config_space.add_hyperparameter(Float("x", bounds=(-5.0, 5.0)))
41
config_space.add_hyperparameter(Float("y", bounds=(-5.0, 5.0)))
42

43
# Define objective function
44
def objective(config: Configuration, seed: int = 0) -> float:
45
    x = config["x"]
46
    y = config["y"]
47
    return x**2 + y**2  # Simple quadratic function
48

49
# Set up scenario
50
scenario = Scenario(
51
    configspace=config_space,
52
    n_trials=100,
53
    name="quadratic_optimization"
54
)
55

56
# Create facade and optimize
57
facade = HyperparameterOptimizationFacade(scenario, objective)
58
incumbent = facade.optimize()
59

60
print(f"Best configuration: {incumbent}")
61
print(f"Best value: {facade.runhistory.get_cost(incumbent)}")
62
```
63

64
Multi-fidelity optimization example:
65

66
```python
67
from smac import MultiFidelityFacade, Scenario
68

69
# Multi-fidelity objective function
70
def multi_fidelity_objective(config: Configuration, seed: int = 0, budget: float = 1.0) -> float:
71
    x = config["x"]
72
    y = config["y"]
73
    # Simulate cost based on budget (more budget = more accurate evaluation)
74
    noise = 1.0 / budget
75
    return x**2 + y**2 + noise * (seed % 10 - 5)
76

77
# Configure scenario with budget range
78
scenario = Scenario(
79
    configspace=config_space,
80
    n_trials=50,
81
    min_budget=0.1,
82
    max_budget=1.0
83
)
84

85
# Use MultiFidelityFacade with Hyperband
86
facade = MultiFidelityFacade(scenario, multi_fidelity_objective)
87
incumbent = facade.optimize()
88
```
89

90
## Architecture
91

92
SMAC3 follows a modular architecture centered around the facade pattern:
93

94
- **Facades**: High-level interfaces (`BlackBoxFacade`, `HyperparameterOptimizationFacade`, etc.) that configure and coordinate optimization components for specific use cases
95
- **Core Classes**: `Scenario` for environment configuration, `RunHistory` for trial management, and `Callback` system for event handling
96
- **Models**: Surrogate models (`GaussianProcess`, `RandomForest`) that learn from trial history to predict performance
97
- **Acquisition**: Functions (`EI`, `PI`, `LCB`) and maximizers that determine the next promising configuration to evaluate
98
- **Intensification**: Strategies (`Intensifier`, `Hyperband`) for comparing configurations and managing multi-fidelity budgets
99
- **Initial Design**: Sampling strategies (`SobolInitialDesign`, `RandomInitialDesign`) for initial exploration
100

101
This design enables easy customization while providing sensible defaults for common optimization scenarios.
102

103
## Capabilities
104

105
### Optimization Facades
106

107
High-level interfaces that pre-configure SMAC components for specific optimization scenarios. Each facade provides static methods to customize individual components while maintaining sensible defaults.
108

109
```python { .api }
110
class BlackBoxFacade(AbstractFacade): ...
111
class HyperparameterOptimizationFacade(AbstractFacade): ...
112
class MultiFidelityFacade(HyperparameterOptimizationFacade): ...
113
class AlgorithmConfigurationFacade(AbstractFacade): ...
114
class RandomFacade(AbstractFacade): ...
115
class HyperbandFacade(RandomFacade): ...
116
```
117

118
[Optimization Facades](./facades.md)
119

120
### Core Framework
121

122
Essential classes for configuring optimization environments, managing trial history, and handling optimization events through callbacks.
123

124
```python { .api }
125
class Scenario: ...
126
class RunHistory: ...
127
class Callback: ...
128
class MetadataCallback: ...
129
class StatusType: ...
130
```
131

132
[Core Framework](./core.md)
133

134
### Trial Management
135

136
Data structures for representing optimization trials, their configurations, results, and execution context.
137

138
```python { .api }
139
class TrialInfo: ...
140
class TrialValue: ...
141
class TrialKey: ...
142
class TrajectoryItem: ...
143
```
144

145
[Trial Management](./trials.md)
146

147
### Advanced Components
148

149
Lower-level components for building custom optimization workflows including surrogate models, acquisition functions, intensifiers, and sampling strategies.
150

151
```python { .api }
152
class AbstractModel: ...
153
class AbstractAcquisitionFunction: ...
154
class AbstractIntensifier: ...
155
class AbstractInitialDesign: ...
156
```
157

158
[Advanced Components](./advanced.md)