ray.tune.schedulers.HyperBandScheduler#

class ray.tune.schedulers.HyperBandScheduler(time_attr: str = 'training_iteration', metric: Optional[str] = None, mode: Optional[str] = None, max_t: int = 81, reduction_factor: float = 3, stop_last_trials: bool = True)[source]#

Bases: ray.tune.schedulers.trial_scheduler.FIFOScheduler

Implements the HyperBand early stopping algorithm.

HyperBandScheduler early stops trials using the HyperBand optimization algorithm. It divides trials into brackets of varying sizes, and periodically early stops low-performing trials within each bracket.

To use this implementation of HyperBand with Tune, all you need to do is specify the max length of time a trial can run max_t, the time units time_attr, the name of the reported objective value metric, and if metric is to be maximized or minimized (mode). We automatically determine reasonable values for the other HyperBand parameters based on the given values.

For example, to limit trials to 10 minutes and early stop based on the episode_mean_reward attr, construct:

HyperBand('time_total_s', 'episode_reward_mean', max_t=600)

Note that Tune’s stopping criteria will be applied in conjunction with HyperBand’s early stopping mechanisms.

See also: https://blog.ml.cmu.edu/2018/12/12/massively-parallel-hyperparameter-optimization/

Parameters

  • time_attr – The training result attr to use for comparing time. Note that you can pass in something non-temporal such as training_iteration as a measure of progress, the only requirement is that the attribute should increase monotonically.

  • metric – The training result objective value attribute. Stopping procedures will use this attribute. If None but a mode was passed, the ray.tune.result.DEFAULT_METRIC will be used per default.

  • mode – One of {min, max}. Determines whether objective is minimizing or maximizing the metric attribute.

  • max_t – max time units per trial. Trials will be stopped after max_t time units (determined by time_attr) have passed. The scheduler will terminate trials after this time has passed. Note that this is different from the semantics of max_t as mentioned in the original HyperBand paper.

  • reduction_factor – Same as eta. Determines how sharp the difference is between bracket space-time allocation ratios.

  • stop_last_trials – Whether to terminate the trials after reaching max_t. Defaults to True.

PublicAPI: This API is stable across Ray releases.

set_search_properties(metric: Optional[str], mode: Optional[str], **spec) → bool[source]#

Pass search properties to scheduler.

This method acts as an alternative to instantiating schedulers that react to metrics with their own metric and mode parameters.

Parameters

  • metric – Metric to optimize

  • mode – One of [“min”, “max”]. Direction to optimize.

  • **spec – Any kwargs for forward compatiblity. Info like Experiment.PUBLIC_KEYS is provided through here.

on_trial_add(trial_runner: ray.tune.execution.trial_runner.TrialRunner, trial: ray.tune.experiment.trial.Trial)[source]#

Adds new trial.

On a new trial add, if current bracket is not filled, add to current bracket. Else, if current band is not filled, create new bracket, add to current bracket. Else, create new iteration, create new bracket, add to bracket.

on_trial_result(trial_runner: ray.tune.execution.trial_runner.TrialRunner, trial: ray.tune.experiment.trial.Trial, result: Dict)[source]#

If bracket is finished, all trials will be stopped.

If a given trial finishes and bracket iteration is not done, the trial will be paused and resources will be given up.

This scheduler will not start trials but will stop trials. The current running trial will not be handled, as the trialrunner will be given control to handle it.

on_trial_remove(trial_runner: ray.tune.execution.trial_runner.TrialRunner, trial: ray.tune.experiment.trial.Trial)[source]#

Notification when trial terminates.

Trial info is removed from bracket. Triggers halving if bracket is not finished.

on_trial_complete(trial_runner: ray.tune.execution.trial_runner.TrialRunner, trial: ray.tune.experiment.trial.Trial, result: Dict)[source]#

Cleans up trial info from bracket if trial completed early.

on_trial_error(trial_runner: ray.tune.execution.trial_runner.TrialRunner, trial: ray.tune.experiment.trial.Trial)[source]#

Cleans up trial info from bracket if trial errored early.

choose_trial_to_run(trial_runner: ray.tune.execution.trial_runner.TrialRunner) → Optional[ray.tune.experiment.trial.Trial][source]#

Fair scheduling within iteration by completion percentage.

List of trials not used since all trials are tracked as state of scheduler. If iteration is occupied (ie, no trials to run), then look into next iteration.

debug_string() → str[source]#

This provides a progress notification for the algorithm.

For each bracket, the algorithm will output a string as follows:

Bracket(Max Size (n)=5, Milestone (r)=33, completed=14.6%): {PENDING: 2, RUNNING: 3, TERMINATED: 2}

“Max Size” indicates the max number of pending/running experiments set according to the Hyperband algorithm.

“Milestone” indicates the iterations a trial will run for before the next halving will occur.

“Completed” indicates an approximate progress metric. Some brackets, like ones that are unfilled, will not reach 100%.