# mlr3tuning Package website: [release](https://mlr3tuning.mlr-org.com/) \| [dev](https://mlr3tuning.mlr-org.com/dev/) *mlr3tuning* is the hyperparameter optimization package of the [mlr3](https://mlr-org.com/) ecosystem. It features highly configurable search spaces via the [paradox](https://github.com/mlr-org/paradox) package and finds optimal hyperparameter configurations for any mlr3 [learner](https://github.com/mlr-org/mlr3learners). mlr3tuning works with several optimization algorithms e.g. Random Search, Iterated Racing, Bayesian Optimization (in [mlr3mbo](https://github.com/mlr-org/mlr3mbo)) and Hyperband (in [mlr3hyperband](https://github.com/mlr-org/mlr3hyperband)). Moreover, it can [automatically](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html#sec-autotuner) optimize learners and estimate the performance of optimized models with [nested resampling](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html#sec-nested-resampling). The package is built on the optimization framework [bbotk](https://github.com/mlr-org/bbotk). ## Extension packages mlr3tuning is extended by the following packages. - [mlr3tuningspaces](https://github.com/mlr-org/mlr3tuningspaces) is a collection of search spaces from scientific articles for commonly used learners. - [mlr3hyperband](https://github.com/mlr-org/mlr3hyperband) adds the Hyperband and Successive Halving algorithm. - [mlr3mbo](https://github.com/mlr-org/mlr3mbo) adds Bayesian Optimization methods. ## Resources There are several sections about hyperparameter optimization in the [mlr3book](https://mlr3book.mlr-org.com). - Getting started with [hyperparameter optimization](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html). - An overview of all tuners can be found on our [website](https://mlr-org.com/tuners.html). - [Tune](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html#sec-model-tuning) a support vector machine on the Sonar data set. - Learn about [tuning spaces](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html#sec-defining-search-spaces). - Estimate the model performance with [nested resampling](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html#sec-nested-resampling). - Learn about [multi-objective optimization](https://mlr3book.mlr-org.com/chapters/chapter5/advanced_tuning_methods_and_black_box_optimization.html#sec-multi-metrics-tuning). - Simultaneously optimize hyperparameters and use [early stopping](https://mlr3book.mlr-org.com/chapters/chapter15/predsets_valid_inttune.html) with XGBoost. - [Automate](https://mlr3book.mlr-org.com/chapters/chapter4/hyperparameter_optimization.html#sec-autotuner) the tuning. The [gallery](https://mlr-org.com/gallery-all-optimization.html) features a collection of case studies and demos about optimization. - Learn more advanced methods with the [Practical Tuning Series](https://mlr-org.com/gallery/series/2021-03-09-practical-tuning-series-tune-a-support-vector-machine/). - Learn about [hotstarting](https://mlr-org.com/gallery/optimization/2023-01-16-hotstart/) models. - Run the [default hyperparameter configuration](https://mlr-org.com/gallery/optimization/2023-01-31-default-configuration/) of learners as a baseline. - Use the [Hyperband](https://mlr-org.com/gallery/series/2023-01-15-hyperband-xgboost/) optimizer with different budget parameters. The [cheatsheet](https://cheatsheets.mlr-org.com/mlr3tuning.pdf) summarizes the most important functions of mlr3tuning. ## Installation Install the last release from CRAN: ``` r install.packages("mlr3tuning") ``` Install the development version from GitHub: ``` r # install.packages("pak") pak::pak("mlr-org/mlr3tuning") ``` ## Examples We optimize the `cost` and `gamma` hyperparameters of a support vector machine on the [Sonar](https://mlr3.mlr-org.com/reference/mlr_tasks_sonar.html) data set. ``` r library("mlr3learners") library("mlr3tuning") learner = lrn("classif.svm", cost = to_tune(1e-5, 1e5, logscale = TRUE), gamma = to_tune(1e-5, 1e5, logscale = TRUE), kernel = "radial", type = "C-classification" ) ``` We construct a tuning instance with the [`ti()`](https://mlr3tuning.mlr-org.com/reference/ti.md) function. The tuning instance describes the tuning problem. ``` r instance = ti( task = tsk("sonar"), learner = learner, resampling = rsmp("cv", folds = 3), measures = msr("classif.ce"), terminator = trm("none") ) instance ``` ``` R ## ## ── ───────────────────────────────────────────────────────────────── ## • State: Not optimized ## • Objective: ## • Search Space: ## id class lower upper nlevels ## 1: cost ParamDbl -11.51293 11.51293 Inf ## 2: gamma ParamDbl -11.51293 11.51293 Inf ## • Terminator: ``` We select a simple grid search as the optimization algorithm. ``` r tuner = tnr("grid_search", resolution = 5) tuner ``` ``` R ## ## ── : Grid Search ───────────────────────────────────────────────────────────── ## • Parameters: batch_size=1, resolution=5 ## • Parameter classes: , , , and ## • Properties: dependencies, single-crit, and multi-crit ## • Packages: mlr3tuning and bbotk ``` To start the tuning, we simply pass the tuning instance to the tuner. ``` r tuner$optimize(instance) ``` ``` R ## cost gamma learner_param_vals x_domain classif.ce ## 1: 5.756463 -5.756463 0.1828847 ``` The tuner returns the best hyperparameter configuration and the corresponding measured performance. The archive contains all evaluated hyperparameter configurations. ``` r as.data.table(instance$archive)[, .(cost, gamma, classif.ce, batch_nr, resample_result)] ``` ``` R ## cost gamma classif.ce batch_nr resample_result ## 1: -5.756463 5.756463 0.4663216 1 ## 2: 5.756463 -5.756463 0.1828847 2 ## 3: 11.512925 5.756463 0.4663216 3 ## 4: 5.756463 11.512925 0.4663216 4 ## 5: -11.512925 -11.512925 0.4663216 5 ## --- ## 21: -5.756463 -5.756463 0.4663216 21 ## 22: 11.512925 11.512925 0.4663216 22 ## 23: -11.512925 11.512925 0.4663216 23 ## 24: 11.512925 -5.756463 0.1828847 24 ## 25: 0.000000 -5.756463 0.2402346 25 ``` The [mlr3viz](https://mlr3viz.mlr-org.com/) package visualizes tuning results. ``` r library(mlr3viz) autoplot(instance, type = "surface") ``` ![](reference/figures/plot.png) We fit a final model with optimized hyperparameters to make predictions on new data. ``` r learner$param_set$values = instance$result_learner_param_vals learner$train(tsk("sonar")) ``` ## Citation If you use mlr3tuning in your work, please cite it. > Becker M, Lang M, Richter J, Bischl B (2026). *mlr3tuning: > Hyperparameter Optimization for mlr3*. , > . ``` R @Manual{becker2026mlr3tuning, title = {mlr3tuning: Hyperparameter Optimization for mlr3}, url = {https://doi.org/10.5281/zenodo.15852621}, author = {Marc Becker and Michel Lang and Jakob Richter and Bernd Bischl}, year = {2026}, doi = {10.5281/zenodo.15852621}, } ``` # Package index ## Tuning Instances - [`TuningInstanceAsyncMultiCrit`](https://mlr3tuning.mlr-org.com/reference/TuningInstanceAsyncMultiCrit.md) : Multi-Criteria Tuning with Rush - [`TuningInstanceAsyncSingleCrit`](https://mlr3tuning.mlr-org.com/reference/TuningInstanceAsyncSingleCrit.md) : Single Criterion Tuning with Rush - [`TuningInstanceBatchMultiCrit`](https://mlr3tuning.mlr-org.com/reference/TuningInstanceBatchMultiCrit.md) : Class for Multi Criteria Tuning - [`TuningInstanceBatchSingleCrit`](https://mlr3tuning.mlr-org.com/reference/TuningInstanceBatchSingleCrit.md) : Class for Single Criterion Tuning - [`TuningInstanceMultiCrit`](https://mlr3tuning.mlr-org.com/reference/TuningInstanceMultiCrit.md) : Multi Criteria Tuning Instance for Batch Tuning - [`TuningInstanceSingleCrit`](https://mlr3tuning.mlr-org.com/reference/TuningInstanceSingleCrit.md) : Single Criterion Tuning Instance for Batch Tuning - [`ti()`](https://mlr3tuning.mlr-org.com/reference/ti.md) : Syntactic Sugar for Tuning Instance Construction - [`ti_async()`](https://mlr3tuning.mlr-org.com/reference/ti_async.md) : Syntactic Sugar for Asynchronous Tuning Instance Construction - [`ObjectiveTuning`](https://mlr3tuning.mlr-org.com/reference/ObjectiveTuning.md) : Class for Tuning Objective - [`ObjectiveTuningAsync`](https://mlr3tuning.mlr-org.com/reference/ObjectiveTuningAsync.md) : Class for Tuning Objective - [`ObjectiveTuningBatch`](https://mlr3tuning.mlr-org.com/reference/ObjectiveTuningBatch.md) : Class for Tuning Objective - [`ArchiveAsyncTuning`](https://mlr3tuning.mlr-org.com/reference/ArchiveAsyncTuning.md) : Rush Data Storage - [`ArchiveAsyncTuningFrozen`](https://mlr3tuning.mlr-org.com/reference/ArchiveAsyncTuningFrozen.md) : Frozen Rush Data Storage - [`ArchiveBatchTuning`](https://mlr3tuning.mlr-org.com/reference/ArchiveBatchTuning.md) : Class for Logging Evaluated Hyperparameter Configurations - [`tune()`](https://mlr3tuning.mlr-org.com/reference/tune.md) : Function for Tuning a Learner ## Tuners - [`Tuner`](https://mlr3tuning.mlr-org.com/reference/Tuner.md) : Tuner - [`TunerAsync`](https://mlr3tuning.mlr-org.com/reference/TunerAsync.md) : Class for Asynchronous Tuning Algorithms - [`TunerBatch`](https://mlr3tuning.mlr-org.com/reference/TunerBatch.md) : Class for Batch Tuning Algorithms - [`mlr_tuners_async_design_points`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_async_design_points.md) [`TunerAsyncDesignPoints`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_async_design_points.md) : Hyperparameter Tuning with Asynchronous Design Points - [`mlr_tuners_async_grid_search`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_async_grid_search.md) [`TunerAsyncGridSearch`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_async_grid_search.md) : Hyperparameter Tuning with Asynchronous Grid Search - [`mlr_tuners_async_random_search`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_async_random_search.md) [`TunerAsyncRandomSearch`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_async_random_search.md) : Hyperparameter Tuning with Asynchronous Random Search - [`mlr_tuners_cmaes`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_cmaes.md) [`TunerBatchCmaes`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_cmaes.md) : Hyperparameter Tuning with Covariance Matrix Adaptation Evolution Strategy - [`mlr_tuners_design_points`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_design_points.md) [`TunerBatchDesignPoints`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_design_points.md) : Hyperparameter Tuning with Design Points - [`mlr_tuners_gensa`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_gensa.md) [`TunerBatchGenSA`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_gensa.md) : Hyperparameter Tuning with Generalized Simulated Annealing - [`mlr_tuners_grid_search`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_grid_search.md) [`TunerBatchGridSearch`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_grid_search.md) : Hyperparameter Tuning with Grid Search - [`mlr_tuners_internal`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_internal.md) [`TunerBatchInternal`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_internal.md) : Hyperparameter Tuning with Internal Tuning - [`mlr_tuners_irace`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_irace.md) [`TunerBatchIrace`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_irace.md) : Hyperparameter Tuning with Iterated Racing. - [`mlr_tuners_nloptr`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_nloptr.md) [`TunerBatchNLoptr`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_nloptr.md) : Hyperparameter Tuning with Non-linear Optimization - [`mlr_tuners_random_search`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_random_search.md) [`TunerBatchRandomSearch`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners_random_search.md) : Hyperparameter Tuning with Random Search - [`mlr_tuners`](https://mlr3tuning.mlr-org.com/reference/mlr_tuners.md) : Dictionary of Tuners - [`tnr()`](https://mlr3tuning.mlr-org.com/reference/tnr.md) [`tnrs()`](https://mlr3tuning.mlr-org.com/reference/tnr.md) : Syntactic Sugar for Tuning Objects Construction - [`AutoTuner`](https://mlr3tuning.mlr-org.com/reference/AutoTuner.md) : Class for Automatic Tuning - [`auto_tuner()`](https://mlr3tuning.mlr-org.com/reference/auto_tuner.md) : Function for Automatic Tuning - [`set_validate(`*``*`)`](https://mlr3tuning.mlr-org.com/reference/set_validate.AutoTuner.md) : Configure Validation for AutoTuner ## Terminators - [`reexports`](https://mlr3tuning.mlr-org.com/reference/reexports.md) [`mlr_terminators`](https://mlr3tuning.mlr-org.com/reference/reexports.md) [`trm`](https://mlr3tuning.mlr-org.com/reference/reexports.md) [`trms`](https://mlr3tuning.mlr-org.com/reference/reexports.md) [`mlr_callbacks`](https://mlr3tuning.mlr-org.com/reference/reexports.md) [`clbk`](https://mlr3tuning.mlr-org.com/reference/reexports.md) [`clbks`](https://mlr3tuning.mlr-org.com/reference/reexports.md) : Objects exported from other packages ## Nested Resampling - [`tune_nested()`](https://mlr3tuning.mlr-org.com/reference/tune_nested.md) : Function for Nested Resampling - [`extract_inner_tuning_archives()`](https://mlr3tuning.mlr-org.com/reference/extract_inner_tuning_archives.md) : Extract Inner Tuning Archives - [`extract_inner_tuning_results()`](https://mlr3tuning.mlr-org.com/reference/extract_inner_tuning_results.md) : Extract Inner Tuning Results ## Callbacks - [`CallbackAsyncTuning`](https://mlr3tuning.mlr-org.com/reference/CallbackAsyncTuning.md) : Asynchronous Tuning Callback - [`CallbackBatchTuning`](https://mlr3tuning.mlr-org.com/reference/CallbackBatchTuning.md) : Create Batch Tuning Callback - [`ContextAsyncTuning`](https://mlr3tuning.mlr-org.com/reference/ContextAsyncTuning.md) : Asynchronous Tuning Context - [`ContextBatchTuning`](https://mlr3tuning.mlr-org.com/reference/ContextBatchTuning.md) : Batch Tuning Context - [`callback_async_tuning()`](https://mlr3tuning.mlr-org.com/reference/callback_async_tuning.md) : Create Asynchronous Tuning Callback - [`callback_batch_tuning()`](https://mlr3tuning.mlr-org.com/reference/callback_batch_tuning.md) : Create Batch Tuning Callback - [`mlr3tuning`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning-package.md) [`mlr3tuning-package`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning-package.md) : mlr3tuning: Hyperparameter Optimization for 'mlr3' - [`mlr3tuning.async_default_configuration`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.async_default_configuration.md) : Default Configuration Callback - [`mlr3tuning.async_freeze_archive`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.async_freeze_archive.md) : Freeze Archive Callback - [`mlr3tuning.async_mlflow`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.async_mlflow.md) : MLflow Connector Callback - [`mlr3tuning.async_save_logs`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.async_save_logs.md) : Save Logs Callback - [`mlr3tuning.backup`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.backup.md) : Backup Benchmark Result Callback - [`mlr3tuning.measures`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.measures.md) [`mlr3tuning.async_measures`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.measures.md) : Measure Callback - [`mlr3tuning.one_se_rule`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning.one_se_rule.md) : One Standard Error Rule Callback - [`assert_async_tuning_callback()`](https://mlr3tuning.mlr-org.com/reference/assert_async_tuning_callback.md) [`assert_async_tuning_callbacks()`](https://mlr3tuning.mlr-org.com/reference/assert_async_tuning_callback.md) : Assertions for Callbacks - [`assert_batch_tuning_callback()`](https://mlr3tuning.mlr-org.com/reference/assert_batch_tuning_callback.md) [`assert_batch_tuning_callbacks()`](https://mlr3tuning.mlr-org.com/reference/assert_batch_tuning_callback.md) : Assertions for Callbacks ## Converters - [`as_search_space()`](https://mlr3tuning.mlr-org.com/reference/as_search_space.md) : Convert to a Search Space - [`as_tuner()`](https://mlr3tuning.mlr-org.com/reference/as_tuner.md) [`as_tuners()`](https://mlr3tuning.mlr-org.com/reference/as_tuner.md) : Convert to a Tuner ## Package - [`mlr3tuning`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning-package.md) [`mlr3tuning-package`](https://mlr3tuning.mlr-org.com/reference/mlr3tuning-package.md) : mlr3tuning: Hyperparameter Optimization for 'mlr3' # Articles ### All vignettes - [Add a new Tuner](https://mlr3tuning.mlr-org.com/articles/extending.md):