ray.tune.search.optuna.OptunaSearch
ray.tune.search.optuna.OptunaSearch#
- class ray.tune.search.optuna.OptunaSearch(space: Optional[Union[Dict[str, <MagicMock name='mock.BaseDistribution' id='140258769882960'>], List[Tuple], Callable[[<MagicMock name='mock.Trial' id='140258768000912'>], Optional[Dict[str, Any]]]]] = None, metric: Optional[Union[str, List[str]]] = None, mode: Optional[Union[str, List[str]]] = None, points_to_evaluate: Optional[List[Dict]] = None, sampler: Optional[<MagicMock name='mock.BaseSampler' id='140258767938064'>] = None, seed: Optional[int] = None, evaluated_rewards: Optional[List] = None)[source]#
Bases:
ray.tune.search.searcher.Searcher
A wrapper around Optuna to provide trial suggestions.
Optuna is a hyperparameter optimization library. In contrast to other libraries, it employs define-by-run style hyperparameter definitions.
This Searcher is a thin wrapper around Optuna’s search algorithms. You can pass any Optuna sampler, which will be used to generate hyperparameter suggestions.
Multi-objective optimization is supported.
- Parameters
space –
Hyperparameter search space definition for Optuna’s sampler. This can be either a
dict
with parameter names as keys andoptuna.distributions
as values, or a Callable - in which case, it should be a define-by-run function usingoptuna.trial
to obtain the hyperparameter values. The function should return either adict
of constant values with names as keys, or None. For more information, see https://optuna.readthedocs.io/en/stable/tutorial/10_key_features/002_configurations.html.Warning
No actual computation should take place in the define-by-run function. Instead, put the training logic inside the function or class trainable passed to
tune.Tuner()
.metric – The training result objective value attribute. If None but a mode was passed, the anonymous metric
_metric
will be used per default. Can be a list of metrics for multi-objective optimization.mode – One of {min, max}. Determines whether objective is minimizing or maximizing the metric attribute. Can be a list of modes for multi-objective optimization (corresponding to
metric
).points_to_evaluate – Initial parameter suggestions to be run first. This is for when you already have some good parameters you want to run first to help the algorithm make better suggestions for future parameters. Needs to be a list of dicts containing the configurations.
sampler –
Optuna sampler used to draw hyperparameter configurations. Defaults to
MOTPESampler
for multi-objective optimization with Optuna<2.9.0, andTPESampler
in every other case. See https://optuna.readthedocs.io/en/stable/reference/samplers/index.html for available Optuna samplers.Warning
Please note that with Optuna 2.10.0 and earlier default
MOTPESampler
/TPESampler
suffer from performance issues when dealing with a large number of completed trials (approx. >100). This will manifest as a delay when suggesting new configurations. This is an Optuna issue and may be fixed in a future Optuna release.seed – Seed to initialize sampler with. This parameter is only used when
sampler=None
. In all other cases, the sampler you pass should be initialized with the seed already.evaluated_rewards –
If you have previously evaluated the parameters passed in as points_to_evaluate you can avoid re-running those trials by passing in the reward attributes as a list so the optimiser can be told the results without needing to re-compute the trial. Must be the same length as points_to_evaluate.
Warning
When using
evaluated_rewards
, the search spacespace
must be provided as adict
with parameter names as keys andoptuna.distributions
instances as values. The define-by-run search space definition is not yet supported with this functionality.
Tune automatically converts search spaces to Optuna’s format:
from ray.tune.search.optuna import OptunaSearch config = { "a": tune.uniform(6, 8) "b": tune.loguniform(1e-4, 1e-2) } optuna_search = OptunaSearch( metric="loss", mode="min") tuner = tune.Tuner( trainable, tune_config=tune.TuneConfig( search_alg=optuna_search, ), param_space=config, ) tuner.fit()
If you would like to pass the search space manually, the code would look like this:
from ray.tune.search.optuna import OptunaSearch import optuna space = { "a": optuna.distributions.UniformDistribution(6, 8), "b": optuna.distributions.LogUniformDistribution(1e-4, 1e-2), } optuna_search = OptunaSearch( space, metric="loss", mode="min") tuner = tune.Tuner( trainable, tune_config=tune.TuneConfig( search_alg=optuna_search, ), ) tuner.fit() # Equivalent Optuna define-by-run function approach: def define_search_space(trial: optuna.Trial): trial.suggest_float("a", 6, 8) trial.suggest_float("b", 1e-4, 1e-2, log=True) # training logic goes into trainable, this is just # for search space definition optuna_search = OptunaSearch( define_search_space, metric="loss", mode="min") tuner = tune.Tuner( trainable, tune_config=tune.TuneConfig( search_alg=optuna_search, ), ) tuner.fit()
Multi-objective optimization is supported:
from ray.tune.search.optuna import OptunaSearch import optuna space = { "a": optuna.distributions.UniformDistribution(6, 8), "b": optuna.distributions.LogUniformDistribution(1e-4, 1e-2), } # Note you have to specify metric and mode here instead of # in tune.TuneConfig optuna_search = OptunaSearch( space, metric=["loss1", "loss2"], mode=["min", "max"]) # Do not specify metric and mode here! tuner = tune.Tuner( trainable, tune_config=tune.TuneConfig( search_alg=optuna_search, ), ) tuner.fit()
You can pass configs that will be evaluated first using
points_to_evaluate
:from ray.tune.search.optuna import OptunaSearch import optuna space = { "a": optuna.distributions.UniformDistribution(6, 8), "b": optuna.distributions.LogUniformDistribution(1e-4, 1e-2), } optuna_search = OptunaSearch( space, points_to_evaluate=[{"a": 6.5, "b": 5e-4}, {"a": 7.5, "b": 1e-3}] metric="loss", mode="min") tuner = tune.Tuner( trainable, tune_config=tune.TuneConfig( search_alg=optuna_search, ), ) tuner.fit()
Avoid re-running evaluated trials by passing the rewards together with
points_to_evaluate
:from ray.tune.search.optuna import OptunaSearch import optuna space = { "a": optuna.distributions.UniformDistribution(6, 8), "b": optuna.distributions.LogUniformDistribution(1e-4, 1e-2), } optuna_search = OptunaSearch( space, points_to_evaluate=[{"a": 6.5, "b": 5e-4}, {"a": 7.5, "b": 1e-3}] evaluated_rewards=[0.89, 0.42] metric="loss", mode="min") tuner = tune.Tuner( trainable, tune_config=tune.TuneConfig( search_alg=optuna_search, ), ) tuner.fit()
New in version 0.8.8.
- set_search_properties(metric: Optional[str], mode: Optional[str], config: Dict, **spec) bool [source]#
Pass search properties to searcher.
This method acts as an alternative to instantiating search algorithms with their own specific search spaces. Instead they can accept a Tune config through this method. A searcher should return
True
if setting the config was successful, orFalse
if it was unsuccessful, e.g. when the search space has already been set.- Parameters
metric – Metric to optimize
mode – One of [“min”, “max”]. Direction to optimize.
config – Tune config dict.
**spec – Any kwargs for forward compatiblity. Info like Experiment.PUBLIC_KEYS is provided through here.
- suggest(trial_id: str) Optional[Dict] [source]#
Queries the algorithm to retrieve the next set of parameters.
- Parameters
trial_id – Trial ID used for subsequent notifications.
- Returns
- Configuration for a trial, if possible.
If FINISHED is returned, Tune will be notified that no more suggestions/configurations will be provided. If None is returned, Tune will skip the querying of the searcher for this step.
- Return type
dict | FINISHED | None
- on_trial_result(trial_id: str, result: Dict)[source]#
Optional notification for result during training.
Note that by default, the result dict may include NaNs or may not include the optimization metric. It is up to the subclass implementation to preprocess the result to avoid breaking the optimization process.
- Parameters
trial_id – A unique string ID for the trial.
result – Dictionary of metrics for current training progress. Note that the result dict may include NaNs or may not include the optimization metric. It is up to the subclass implementation to preprocess the result to avoid breaking the optimization process.
- on_trial_complete(trial_id: str, result: Optional[Dict] = None, error: bool = False)[source]#
Notification for the completion of trial.
Typically, this method is used for notifying the underlying optimizer of the result.
- Parameters
trial_id – A unique string ID for the trial.
result – Dictionary of metrics for current training progress. Note that the result dict may include NaNs or may not include the optimization metric. It is up to the subclass implementation to preprocess the result to avoid breaking the optimization process. Upon errors, this may also be None.
error – True if the training process raised an error.
- add_evaluated_point(parameters: Dict, value: float, error: bool = False, pruned: bool = False, intermediate_values: Optional[List[float]] = None)[source]#
Pass results from a point that has been evaluated separately.
This method allows for information from outside the suggest - on_trial_complete loop to be passed to the search algorithm. This functionality depends on the underlying search algorithm and may not be always available.
- Parameters
parameters – Parameters used for the trial.
value – Metric value obtained in the trial.
error – True if the training process raised an error.
pruned – True if trial was pruned.
intermediate_values – List of metric values for intermediate iterations of the result. None if not applicable.
- save(checkpoint_path: str)[source]#
Save state to path for this search algorithm.
- Parameters
checkpoint_path – File where the search algorithm state is saved. This path should be used later when restoring from file.
Example:
search_alg = Searcher(...) tuner = tune.Tuner( cost, tune_config=tune.TuneConfig( search_alg=search_alg, num_samples=5 ), param_space=config ) results = tuner.fit() search_alg.save("./my_favorite_path.pkl")
Changed in version 0.8.7: Save is automatically called by
Tuner().fit()
. You can useTuner().restore()
to restore from an experiment directory such as/ray_results/trainable
.
- restore(checkpoint_path: str)[source]#
Restore state for this search algorithm
- Parameters
checkpoint_path – File where the search algorithm state is saved. This path should be the same as the one provided to “save”.
Example:
search_alg.save("./my_favorite_path.pkl") search_alg2 = Searcher(...) search_alg2 = ConcurrencyLimiter(search_alg2, 1) search_alg2.restore(checkpoint_path) tuner = tune.Tuner( cost, tune_config=tune.TuneConfig( search_alg=search_alg2, num_samples=5 ), ) tuner.fit()