class_docstr: 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/
  
  Args:
      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.
class_docstr_tok: ["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\/","Args",":","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","."]
docstr: 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.
docstr_tok: ["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","."]
code: def choose_trial_to_run(
      self, tune_controller: "TuneController"
  ) -> Optional[Trial]:
      """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.
      """
  
      for hyperband in self._hyperbands:
          # band will have None entries if no resources
          # are to be allocated to that bracket.
          scrubbed = [b for b in hyperband if b is not None]
          for bracket in sorted(
              scrubbed, key=lambda b: b.completion_percentage()
          ):
              for trial in bracket.current_trials():
                  if (
                      trial.status == Trial.PAUSED
                      and trial in bracket.trials_to_unpause
                  ) or trial.status == Trial.PENDING:
                      return trial
      return None
  
imports: import collections
  from typing import Dict, List, Optional, Tuple, TYPE_CHECKING
  import numpy
  import logging
  from ray.util.annotations import PublicAPI
  from ray.tune.result import DEFAULT_METRIC
  from ray.tune.schedulers.trial_scheduler import FIFOScheduler, TrialScheduler
  from ray.tune.experiment import Trial
  from ray.tune.error import TuneError
label_desc: Use image node_id 12 for calling the HyperBandScheduler obj's underlying member method code with example usage: obj.choose_trial_to_run(tune_controller) and returns: None, trial