PBT implementation

docs/src/code/algo.rst

@@ -2,8 +2,6 @@
 Algorithm modules
 *****************
 
-TODO
-
 .. automodule:: orion.algo
    :members:
 
@@ -17,5 +15,6 @@ TODO
    algo/gridsearch
    algo/hyperband
    algo/asha
+   algo/pbt
    algo/tpe
    algo/parallel_strategy

docs/src/code/algo/asha.rst

@@ -1,8 +1,5 @@
 Asynchronous Successive Halving Algorithm
 =========================================
 
-Can't build documentation because of import order.
-Sphinx is loading ``orion.algo.asha`` before ``orion.algo`` and therefore
-there is a cycle between the definition of ``BaseAlgorithm`` and
-``ASHA`` as the meta-class ``Factory`` is trying to import ``ASHA``.
-`PR #135 <https://github.com/Epistimio/orion/pull/135/files>`_ should get rid of this problem.
+.. automodule:: orion.algo.asha
+   :members:

docs/src/code/algo/base.rst

@@ -3,5 +3,3 @@ Base definition of algorithms
 
 .. autoclass:: orion.algo.base.BaseAlgorithm
    :members:
-
-

docs/src/code/algo/pbt.rst

@@ -0,0 +1,89 @@
+Population Based Training
+=========================
+
+.. contents::
+   :depth: 3
+   :local:
+
+.. role:: hidden
+    :class: hidden-section
+
+Population Based Training
+-------------------------
+
+.. autoclass:: orion.algo.pbt.pbt.PBT
+   :members:
+
+LineageNode
+-----------
+
+.. autoclass:: orion.algo.pbt.pbt.LineageNode
+   :members:
+
+Lineages
+--------
+
+.. autoclass:: orion.algo.pbt.pbt.Lineages
+   :members:
+
+Exploit classes for Population Based Training
+---------------------------------------------
+
+BaseExploit
+~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.exploit.BaseExploit
+   :members:
+
+
+PipelineExploit
+~~~~~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.exploit.PipelineExploit
+   :members:
+
+
+TruncateExploit
+~~~~~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.exploit.TruncateExploit
+   :members:
+
+BacktrackExploit
+~~~~~~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.exploit.BacktrackExploit
+   :members:
+
+Explore classes for Population Based Training
+---------------------------------------------
+
+BaseExplore
+~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.explore.BaseExplore
+   :members:
+
+
+PipelineExplore
+~~~~~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.explore.PipelineExplore
+   :members:
+
+
+PerturbExplore
+~~~~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.explore.PerturbExplore
+   :members:
+
+ResampleExplore
+~~~~~~~~~~~~~~~
+
+.. autoclass:: orion.algo.pbt.explore.ResampleExplore
+   :members:
+
+
+
+

docs/src/code/core/evc.rst

@@ -8,7 +8,6 @@ Experiment Version Control
    :maxdepth: 1
    :caption: Modules
 
-   evc/tree
    evc/experiment
    evc/adapters
    evc/conflicts

docs/src/code/core/utils.rst

@@ -9,6 +9,7 @@ Utilities
    utils/format_trials
    utils/format_terminal
    utils/singleton
+   utils/tree
 
 .. automodule:: orion.core.utils
    :members:

docs/src/code/core/evc/tree.rst → docs/src/code/core/utils/tree.rst

@@ -1,5 +1,5 @@
 Generic Tree
 ============
 
-.. automodule:: orion.core.evc.tree
+.. automodule:: orion.core.utils.tree
    :members:

docs/src/user/algorithms.rst

@@ -212,6 +212,69 @@ Configuration
                      executed_times, compute_bracket_idx
 
 
+.. _PBT:
+
+Population Based Training (PBT)
+-------------------------------
+
+Population based training is an evolutionary algorithm that evolve trials
+from low fidelity levels to high fidelity levels (ex: number of epochs), reusing
+the model's parameters along the way. This has the effect of creating hyperparameter
+schedules through the fidelity levels.
+
+See documentation below for more information on the algorithm and how to use it.
+
+.. note::
+
+   Current implementation does not support more than one fidelity dimension.
+
+Configuration
+~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+  experiment:
+
+    strategy: StubParallelStrategy
+
+    algorithms:
+      pbt:
+        population_size: 50
+        generations: 10
+        fork_timeout: 60
+        exploit:
+          of_type: PipelineExploit
+          exploit_configs:
+            - of_type: BacktrackExploit
+              min_forking_population: 5
+              truncation_quantile: 0.9
+              candidate_pool_ratio: 0.2
+            - of_type: TruncateExploit
+              min_forking_population: 5
+              truncation_quantile: 0.8
+              candidate_pool_ratio: 0.2
+         explore:
+           of_type: PipelineExplore
+           explore_configs:
+             - of_type: ResampleExplore
+               probability: 0.2
+             - of_type: PerturbExplore
+               factor: 1.2
+               volatility: 0.0001
+
+
+
+.. note::
+   Notice the additional ``strategy`` in configuration which is not mandatory for most other
+   algorithms. See :ref:`StubParallelStrategy` for more information.
+
+
+.. autoclass:: orion.algo.pbt.pbt.PBT
+   :noindex:
+   :exclude-members: space, state_dict, set_state, suggest, observe, is_done, seed_rng,
+                     configuration, requires_type, rng, register
+
+
 
 .. _tpe-algorithm:
 

setup.py

@@ -16,6 +16,7 @@
 
 packages = [  # Packages must be sorted alphabetically to ease maintenance and merges.
     "orion.algo",
+    "orion.algo.pbt",
     "orion.analysis",
     "orion.benchmark",
     "orion.client",
@@ -53,6 +54,7 @@
             "hyperband = orion.algo.hyperband:Hyperband",
             "tpe = orion.algo.tpe:TPE",
             "EvolutionES = orion.algo.evolution_es:EvolutionES",
+            "pbt = orion.algo.pbt.pbt:PBT",
         ],
         "Database": [
             "ephemeraldb = orion.core.io.database.ephemeraldb:EphemeralDB",

src/orion/algo/base.py

@@ -161,7 +161,7 @@ def format_trial(self, trial):
 
         return trial
 
-    def get_id(self, trial, ignore_fidelity=False):
+    def get_id(self, trial, ignore_fidelity=False, ignore_parent=False):
         """Return unique hash for a trials based on params
 
         The trial is assumed to be in the transformed space if the algorithm is working in a
@@ -174,6 +174,10 @@ def get_id(self, trial, ignore_fidelity=False):
         ignore_fidelity: bool, optional
             If True, the fidelity dimension is ignored when computing a unique hash for
             the trial. Defaults to False.
+        ignore_parent: bool, optional
+            If True, the parent id is ignored when computing a unique hash for
+            the trial. Defaults to False.
+
         """
 
         # Apply transforms and reverse to see data as it would come from DB
@@ -188,6 +192,7 @@ def get_id(self, trial, ignore_fidelity=False):
             ignore_fidelity=ignore_fidelity,
             ignore_experiment=True,
             ignore_lie=True,
+            ignore_parent=ignore_parent,
         )
 
     @property
@@ -357,8 +362,8 @@ def judge(self, trial, measurements):  # pylint:disable=no-self-use,unused-argum
         trial: ``orion.core.worker.trial.Trial``
            Trial object to retrieve from the database
 
-        Notes:
-        ------
+        Notes
+        -----
 
         Calling algorithm to `judge` a `point` based on its online `measurements` will effectively
         change a state in the algorithm (like a reinforcement learning agent's hidden state or an

src/orion/algo/hyperband.py

@@ -192,8 +192,10 @@ def sample_from_bracket(self, bracket, num):
                 params={self.fidelity_index: bracket.rungs[0]["resources"]}
             )
 
-            full_id = self.get_id(trial, ignore_fidelity=False)
-            id_wo_fidelity = self.get_id(trial, ignore_fidelity=True)
+            full_id = self.get_id(trial, ignore_fidelity=False, ignore_parent=False)
+            id_wo_fidelity = self.get_id(
+                trial, ignore_fidelity=True, ignore_parent=True
+            )
 
             bracket_id = self.trial_to_brackets.get(id_wo_fidelity, None)
             if bracket_id is not None:
@@ -262,7 +264,7 @@ def set_state(self, state_dict):
 
     def register_samples(self, bracket, samples):
         for sample in samples:
-            full_id = self.get_id(sample, ignore_fidelity=False)
+            full_id = self.get_id(sample, ignore_fidelity=False, ignore_parent=False)
             if self.has_observed(sample):
                 raise RuntimeError(
                     "Hyperband resampling a trial that was already completed. "
@@ -273,9 +275,12 @@ def register_samples(self, bracket, samples):
             self.register(sample)
             bracket.register(sample)
 
-            if self.get_id(sample, ignore_fidelity=True) not in self.trial_to_brackets:
+            if (
+                self.get_id(sample, ignore_fidelity=True, ignore_parent=True)
+                not in self.trial_to_brackets
+            ):
                 self.trial_to_brackets[
-                    self.get_id(sample, ignore_fidelity=True)
+                    self.get_id(sample, ignore_fidelity=True, ignore_parent=True)
                 ] = self.brackets.index(bracket)
 
     def promote(self, num):
@@ -384,7 +389,7 @@ def create_brackets(self):
 
     def _get_bracket(self, trial):
         """Get the bracket of a trial"""
-        _id_wo_fidelity = self.get_id(trial, ignore_fidelity=True)
+        _id_wo_fidelity = self.get_id(trial, ignore_fidelity=True, ignore_parent=True)
         return self.brackets[self.trial_to_brackets[_id_wo_fidelity]]
 
     def observe(self, trials):
@@ -474,7 +479,9 @@ def is_filled(self):
     def get_trial_max_resource(self, trial):
         """Return the max resource value that has been tried for a trial"""
         max_resource = 0
-        _id_wo_fidelity = self.hyperband.get_id(trial, ignore_fidelity=True)
+        _id_wo_fidelity = self.hyperband.get_id(
+            trial, ignore_fidelity=True, ignore_parent=True
+        )
         for rung in self.rungs:
             if _id_wo_fidelity in rung["results"]:
                 max_resource = rung["resources"]
@@ -511,7 +518,9 @@ def sample(self, num):
 
     def register(self, trial):
         """Register a trial in the corresponding rung"""
-        self._get_results(trial)[self.hyperband.get_id(trial, ignore_fidelity=True)] = (
+        self._get_results(trial)[
+            self.hyperband.get_id(trial, ignore_fidelity=True, ignore_parent=True)
+        ] = (
             trial.objective.value if trial.objective else None,
             copy.deepcopy(trial),
         )
@@ -562,7 +571,7 @@ def get_candidates(self, rung_id):
         while len(trials) + len(next_rung) < should_have_n_trials:
             objective, trial = rung[i]
             assert objective is not None
-            _id = self.hyperband.get_id(trial, ignore_fidelity=True)
+            _id = self.hyperband.get_id(trial, ignore_fidelity=True, ignore_parent=True)
             if _id not in next_rung:
                 trials.append(trial)
             i += 1