class_docstr: Bracket of rungs for the algorithm Hyperband.
  
  Parameters
  ----------
  owner: `Hyperband` algorithm
      The hyperband algorithm object which this bracket will be part of.
  budgets: list of tuple
      Each tuple gives the (n_trials, resource_budget) for the respective rung.
  repetition_id: int
      The id of hyperband execution this bracket belongs to
docstr: Promote the first candidate that is found and return it
  
  The rungs are iterated over in reversed order, so that high rungs
  are prioritised for promotions. When a candidate is promoted, the loop is broken and
  the method returns the promoted trial.
  
  .. note ::
  
      All trials are part of the rungs, for any state. Only completed trials
      are eligible for promotion, i.e., only completed trials can be part of top-k.
      Lookup for promotion in rung l + 1 contains trials of any status.
docstr_tok: ["Promote","the","first","candidate","that","is","found","and","return","it","The","rungs","are","iterated","over","in","reversed","order",",","so","that","high","rungs","are","prioritised","for","promotions",".","When","a","candidate","is","promoted",",","the","loop","is","broken","and","the","method","returns","the","promoted","trial",".","..","note",":",":","All","trials","are","part","of","the","rungs",",","for","any","state",".","Only","completed","trials","are","eligible","for","promotion",",","i.e.",",","only","completed","trials","can","be","part","of","top-k.","Lookup","for","promotion","in","rung","l","+","1","contains","trials","of","any","status","."]
code: def promote(self, num: int) -> list[Trial]:
      """Promote the first candidate that is found and return it
  
      The rungs are iterated over in reversed order, so that high rungs
      are prioritised for promotions. When a candidate is promoted, the loop is broken and
      the method returns the promoted trial.
  
      .. note ::
  
          All trials are part of the rungs, for any state. Only completed trials
          are eligible for promotion, i.e., only completed trials can be part of top-k.
          Lookup for promotion in rung l + 1 contains trials of any status.
  
      """
      if self.is_done:
          return []
  
      for rung_id in range(len(self.rungs)):
          # No more promotion possible, skip to next rung
          if self.has_rung_filled(rung_id + 1):
              continue
  
          if not self.is_ready(rung_id):
              return []
  
          trials = []
          for candidate in self.get_candidates(rung_id):
              # pylint: disable=logging-format-interpolation,consider-using-f-string
              logger.debug(
                  "Promoting {trial} from rung {past_rung} with fidelity {past_fidelity} to "
                  "rung {new_rung} with fidelity {new_fidelity}".format(
                      trial=candidate,
                      past_rung=rung_id,
                      past_fidelity=flatten(candidate.params)[
                          self.owner.fidelity_index
                      ],
                      new_rung=rung_id + 1,
                      new_fidelity=self.rungs[rung_id + 1]["resources"],
                  )
              )
  
              candidate = candidate.branch(
                  status="new",
                  params={
                      self.owner.fidelity_index: self.rungs[
                          rung_id + 1
                      ]["resources"]
                  },
              )
              # NOTE: We could use branching with data folder copy like it is done in
              #       PBT to support checkpointing. This would require adapting the
              #       documentation however, and perhaps make sure trial.hash_params
              #       does not take into account trial.parent otherwise it will change
              #       the id although we ignore the fidelity dimension.
              candidate.parent = None
              if not self.owner.has_suggested(candidate):
                  trials.append(candidate)
  
          return trials[:num]
  
      return []
  
imports: from __future__ import annotations
  import copy
  import logging
  from collections import OrderedDict
  from typing import Any, Generic, NamedTuple, Sequence, TypeVar
  import numpy
  from tabulate import tabulate
  from orion.algo.base import BaseAlgorithm
  from orion.algo.space import Fidelity, Space
  from orion.core.utils.flatten import flatten
  from orion.core.worker.trial import Trial
label_desc: Use image node_id 16 for calling the HyperbandBracket obj's underlying member method code with example usage: obj.promote(num) and returns: list, list, trials, list