Skip to main content
Version: Next

Optuna Sweeper plugin

PyPI PyPI - License PyPI - Python Version PyPI - Downloads Example Example

This plugin enables Hydra applications to utilize Optuna for the optimization of the parameters of experiments.

Installation#

This plugin requires hydra-core>=1.1.0. Currently, only the pre-release version is available. Please install it with the following command:

pip install --pre hydra-core

You can install the plugin via pip:

pip install hydra-optuna-sweeper --upgrade

There are several standard approaches for configuring plugins. Check this page for more information.

Usage#

Please set hydra/sweeper to optuna in your config file.

defaults:  - override hydra/sweeper: optuna

Alternatively, add hydra/sweeper=optuna option to your command line.

The default configuration is here.

Example 1: Single-Objective Optimization#

We include an example in this directory. example/sphere.py implements a simple benchmark function to be minimized.

You can discover the Optuna sweeper parameters with:

python example/sphere.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper
# @package hydra.sweepersampler:  _target_: optuna.samplers.TPESampler  seed: 123  consider_prior: true  prior_weight: 1.0  consider_magic_clip: true  consider_endpoints: false  n_startup_trials: 10  n_ei_candidates: 24  multivariate: false  warn_independent_sampling: true_target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeperdirection: minimizestorage: nullstudy_name: spheren_trials: 20n_jobs: 1search_space:  x:    type: float    low: -5.5    high: 5.5    step: 0.5  'y':    type: categorical    choices:    - -5    - 0    - 5

The function decorated with @hydra.main() returns a float which we want to minimize, the minimum is 0 and reached for:

x: 0y: 0

To run optimization, clone the code and run the following command in the plugins/hydra_optuna_sweeper directory:

python example/sphere.py --multirun

You can also override the search space parametrization:

python example/sphere.py --multirun 'x=interval(-5.0, 5.0)' 'y=interval(0, 10)'

Sampler configuration#

This plugin supports Optuna's samplers. You can change the sampler by overriding hydra/sweeper/sampler or change sampler settings within hydra.sweeper.sampler.

Search space configuration#

This plugin supports Optuna's distributions to configure search spaces. They can be defined either through commandline override or config file.

Configuring through commandline override#

Hydra provides a override parser that support rich syntax. Please refer to OverrideGrammer/Basic and OverrideGrammer/Extended for details.

Interval override#

By default, interval is converted to UniformDistribution. You can use IntUniformDistribution, LogUniformDistribution or IntLogUniformDistribution by casting the interval to int and tagging it with log.

Example for interval override
python example/sphere.py --multirun 'x=int(interval(-5.0, 5.0))' 'y=tag(log, interval(1, 10))'

The output is as follows:

[HYDRA] Study name: sphere[HYDRA] Storage: None[HYDRA] Sampler: TPESampler[HYDRA] Directions: ['minimize'][HYDRA] Launching 1 jobs locally[HYDRA]     #0 : x=-3 y=1.6859762540733367[HYDRA] Launching 1 jobs locally[HYDRA]     #1 : x=1 y=5.237816870668193...[HYDRA] Best parameters: {'x': 0, 'y': 1.0929184723430116}[HYDRA] Best value: 1.1944707871885822

Range override#

range is converted to IntUniformDistribution. If you apply shuffle to range, CategoricalDistribution is used instead.

Example for range override
python example/sphere.py --multirun 'x=range(-5.0, 5.0)' 'y=shuffle(range(-5, 5))'

The output is as follows:

[HYDRA] Study name: sphere[HYDRA] Storage: None[HYDRA] Sampler: TPESampler[HYDRA] Directions: ['minimize'][HYDRA] Launching 1 jobs locally[HYDRA]     #0 : x=-3 y=-4[HYDRA] Launching 1 jobs locally[HYDRA]     #1 : x=1 y=-1...[HYDRA] Best parameters: {'x': 0, 'y': -1}[HYDRA] Best value: 1.0

Choice override#

choice is converted to CategoricalDistribution.

Example for choice override
python example/sphere.py --multirun 'x=choice(-5.0, 0.0, 5.0)' 'y=choice(0, 1, 2, 3, 4, 5)'

The output is as follows:

[HYDRA] Study name: sphere[HYDRA] Storage: None[HYDRA] Sampler: TPESampler[HYDRA] Directions: ['minimize'][HYDRA] Launching 1 jobs locally[HYDRA]     #0 : x=5.0 y=5[HYDRA] Launching 1 jobs locally[HYDRA]     #1 : x=5.0 y=2...[HYDRA] Best parameters: {'x': 0.0, 'y': 0}[HYDRA] Best value: 0.0

Configuring through config file#

Int parameters#

int parameters can be defined with the following fields:

  • type: int
  • low: lower bound
  • high: upper bound
  • step: discretization step (optional)
  • log: if true, space is converted to the log domain

If log is false, the parameter is mapped to IntUniformDistribution. Otherwise, the parameter is mapped to IntLogUniformDistribution. Please note that step can not be set if log=true.

Float parameters#

float parameters can be defined with the following fields:

  • type: float
  • low: lower bound
  • high: upper bound
  • step: discretization step
  • log: if true, space is converted to the log domain

If log is false, the parameter is mapped to UniformDistribution or DiscreteUniformDistribution depending on the presence or absence of the step field, respectively. Otherwise, the parameter is mapped to LogUniformDistribution. Please note that step can not be set if log=true.

Categorical parameters#

categorical parameters can be defined with the following fields:

  • type: categorical
  • choices: a list of parameter value candidates

The parameters are mapped to CategoricalDistribution.

Example 2: Multi-Objective Optimization#

In the same directory, example/multi-objective.py implements a simple benchmark function, which has two objective values. We want to minimize two objectives simultaneously.

You can discover the Optuna sweeper parameters with:

python example/multi-objective.py hydra/sweeper=optuna --cfg hydra -p hydra.sweeper
Configuration of the multi-objective optimization example
# @package hydra.sweepersampler:  _target_: optuna.samplers.NSGAIISampler  seed: 123  population_size: 50  mutation_prob: null  crossover_prob: 0.9  swapping_prob: 0.5  constraints_func: null_target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeperdirection:- minimize- minimizestorage: nullstudy_name: multi-objectiven_trials: 20n_jobs: 1search_space:  x:    type: float    low: 0    high: 5    step: 0.5  'y':    type: float    low: 0    high: 3    step: 0.5

To run the optimization, use the following command in the plugins/hydra_optuna_sweeper directory:

python example/multi-objective.py --multirun

For problems with trade-offs between two different objectives, there may be no single solution that simultaneously minimizes both objectives. Instead, we obtained a set of solutions, namely Pareto optimal solutions, that show the best trade-offs possible between the objectives. In the following figure, the blue dots show the Pareto optimal solutions in the optimization results.

Pareto-optimal solutions