automl/SMAC3

SMAC3: A Versatile Bayesian Optimization Package for Hyperparameter Optimization

SMAC offers a robust and flexible framework for Bayesian Optimization to support users in determining well-performing hyperparameter configurations for their (Machine Learning) algorithms, datasets and applications at hand. The main core consists of Bayesian Optimization in combination with an aggressive racing mechanism to efficiently decide which of two configurations performs better.

SMAC3 is written in Python3 and continuously tested with Python 3.8, 3.9, and 3.10 (and works with newer python versions). Its Random Forest is written in C++. In further texts, SMAC is representatively mentioned for SMAC3.

Documentation

Roadmap

Important: Changes in v2.0

With the next big major release of SMAC, we drastically boosted the user experience by improving the APIs and how the pipelining is done (see changelog). All facades/intensifiers support multi-objective, multi-fidelity, and multi-threading natively now! That includes having an ask-and-tell interface and continuing a run wherever you left off. pSMAC is removed because when specifying the number of workers, SMAC automatically uses multi-threading for evaluating trials. When cleaning the code base, however, we removed the command-line interface (calling a target function from a script is still supported), and runtime optimization. Also, python 3.7 is not supported anymore. If you depend on those functionalities, please keep using v1.4.

We are excited to introduce the new major release and look forward to developing new features on the new code base. We hope you enjoy this new user experience as much as we do. 🚀

Installation

This instruction is for the installation on a Linux system, for Windows and Mac and further information see the documentation.

Create a new environment with python 3.10. We demonstrate the installation via anaconda in the following:

Create and activate environment:

conda create -n SMAC python=3.10
conda activate SMAC

Install SMAC via PyPI:

pip install smac

If you want to contribute to SMAC, use the following steps instead:

git clone https://github.com/automl/SMAC3.git && cd SMAC3
make install-dev

Running SMAC with pyrfr

starting from 2.4.0, SMAC uses random forest from sklearn instead of random forest from pyrfr as the default surrogate model for HPO tasks. However, you could still use the old pyrfr surrogate model by calling smac.facade.old.HyperparameterOptimizationRFRFacade and smac.facade.old.MultiFidelityRFRFacade.

To work with pyrfr, you need to first install gcc, gxx, and swig:

conda install gxx_linux-64 gcc_linux-64 swig

then install smac with the pyrfr option:

pip install smac[pyrfr]

Minimal Example

from ConfigSpace import Configuration, ConfigurationSpace

import numpy as np
from smac import HyperparameterOptimizationFacade, Scenario
from sklearn import datasets
from sklearn.svm import SVC
from sklearn.model_selection import cross_val_score

iris = datasets.load_iris()


def train(config: Configuration, seed: int = 0) -> float:
    classifier = SVC(C=config["C"], random_state=seed)
    scores = cross_val_score(classifier, iris.data, iris.target, cv=5)
    return 1 - np.mean(scores)


configspace = ConfigurationSpace({"C": (0.100, 1000.0)})

# Scenario object specifying the optimization environment
scenario = Scenario(configspace, deterministic=True, n_trials=200)

# Use SMAC to find the best configuration/hyperparameters
smac = HyperparameterOptimizationFacade(scenario, train)
incumbent = smac.optimize()

More examples can be found in the documentation.

Visualization via DeepCAVE

With DeepCAVE (Repo, Paper) you can visualize your SMAC runs. It is a visualization and analysis tool for AutoML (especially for the sub-problem hyperparameter optimization) runs.

License

This program is free software: you can redistribute it and/or modify it under the terms of the 3-clause BSD license (please see the LICENSE file).

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the 3-clause BSD license along with this program (see LICENSE file). If not, see here.

Contacting us

If you have trouble using SMAC, a concrete question or found a bug, please create an issue. This is the easiest way to communicate about these things with us.

For all other inquiries, please write an email to smac[at]ai[dot]uni[dash]hannover[dot]de.

Miscellaneous

SMAC3 is developed by the AutoML Groups of the Universities of Hannover and Freiburg. It is a featured optimizer on AutoML Space.

If you have found a bug, please report to issues. Moreover, we are appreciating any kind of help. Find our guidelines for contributing to this package here.

If you use SMAC in one of your research projects, please cite our JMLR paper:

@article{JMLR:v23:21-0888,
  author  = {Marius Lindauer and Katharina Eggensperger and Matthias Feurer and André Biedenkapp and Difan Deng and Carolin Benjamins and Tim Ruhkopf and René Sass and Frank Hutter},
  title   = {SMAC3: A Versatile Bayesian Optimization Package for Hyperparameter Optimization},
  journal = {Journal of Machine Learning Research},
  year    = {2022},
  volume  = {23},
  number  = {54},
  pages   = {1--9},
  url     = {http://jmlr.org/papers/v23/21-0888.html}
}

Copyright (c) 2025, Leibniz University Hannover - Institute of AI