[tune] Tune Facelift (#2472)

This PR introduces the following changes:

 * Ray Tune -> Tune 
 * [breaking] Creation of `schedulers/`, moving PBT, HyperBand into a submodule
 * [breaking] Search Algorithms now must take in experiment configurations via `add_configurations` rather through initialization
 * Support `"run": (function | class | str)` with automatic registering of trainable
 * Documentation Changes

python/ray/tune/experiment.py

@@ -2,8 +2,13 @@ from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 
+import copy
+import six
+import types
+
 from ray.tune.result import DEFAULT_RESULTS_DIR
 from ray.tune.error import TuneError
+from ray.tune.registry import register_trainable
 
 
 class Experiment(object):
@@ -11,19 +16,21 @@ class Experiment(object):
 
     Parameters:
         name (str): Name of experiment.
-        run (str): The algorithm or model to train. This may refer to the
-            name of a built-on algorithm (e.g. RLLib's DQN or PPO), or a
-            user-defined trainable function or class
-            registered in the tune registry.
+        run (function|class|str): The algorithm or model to train.
+            This may refer to the name of a built-on algorithm
+            (e.g. RLLib's DQN or PPO), a user-defined trainable
+            function or class, or the string identifier of a
+            trainable function or class registered in the tune registry.
         stop (dict): The stopping criteria. The keys may be any field in
             the return result of 'train()', whichever is reached first.
             Defaults to empty dict.
-        config (dict): Algorithm-specific configuration
-            (e.g. env, hyperparams). Defaults to empty dict.
+        config (dict): Algorithm-specific configuration for Tune variant
+            generation (e.g. env, hyperparams). Defaults to empty dict.
+            Custom search algorithms may ignore this.
         trial_resources (dict): Machine resources to allocate per trial,
             e.g. ``{"cpu": 64, "gpu": 8}``. Note that GPUs will not be
             assigned unless you specify them here. Defaults to 1 CPU and 0
-            GPUs.
+            GPUs in ``Trainable.default_resource_request()``.
         repeat (int): Number of times to repeat each trial. Defaults to 1.
         local_dir (str): Local dir to save training results to.
             Defaults to ``~/ray_results``.
@@ -34,6 +41,29 @@ class Experiment(object):
         max_failures (int): Try to recover a trial from its last
             checkpoint at least this many times. Only applies if
             checkpointing is enabled. Defaults to 3.
+        restore (str): Path to checkpoint. Only makes sense to set if
+            running 1 trial. Defaults to None.
+
+
+    Examples:
+        >>> experiment_spec = Experiment(
+        >>>     "my_experiment_name",
+        >>>     my_func,
+        >>>     stop={"mean_accuracy": 100},
+        >>>     config={
+        >>>         "alpha": tune.grid_search([0.2, 0.4, 0.6]),
+        >>>         "beta": tune.grid_search([1, 2]),
+        >>>     },
+        >>>     trial_resources={
+        >>>         "cpu": 1,
+        >>>         "gpu": 0
+        >>>     },
+        >>>     repeat=10,
+        >>>     local_dir="~/ray_results",
+        >>>     upload_dir="s3://your_bucket/path",
+        >>>     checkpoint_freq=10,
+        >>>     max_failures=2)
+
     """
 
     def __init__(self,
@@ -46,20 +76,19 @@ class Experiment(object):
                  local_dir=None,
                  upload_dir="",
                  checkpoint_freq=0,
-                 max_failures=3):
+                 max_failures=3,
+                 restore=None):
         spec = {
-            "run": run,
+            "run": self._register_if_needed(run),
             "stop": stop or {},
             "config": config or {},
-            "trial_resources": trial_resources or {
-                "cpu": 1,
-                "gpu": 0
-            },
+            "trial_resources": trial_resources,
             "repeat": repeat,
             "local_dir": local_dir or DEFAULT_RESULTS_DIR,
             "upload_dir": upload_dir,
             "checkpoint_freq": checkpoint_freq,
-            "max_failures": max_failures
+            "max_failures": max_failures,
+            "restore": restore
         }
 
         self.name = name
@@ -75,11 +104,56 @@ class Experiment(object):
         """
         if "run" not in spec:
             raise TuneError("No trainable specified!")
-        exp = cls(name, spec["run"])
-        exp.name = name
-        exp.spec = spec
+
+        # Special case the `env` param for RLlib by automatically
+        # moving it into the `config` section.
+        if "env" in spec:
+            spec["config"] = spec.get("config", {})
+            spec["config"]["env"] = spec["env"]
+            del spec["env"]
+
+        spec = copy.deepcopy(spec)
+
+        run_value = spec.pop("run")
+        try:
+            exp = cls(name, run_value, **spec)
+        except TypeError:
+            raise TuneError("Improper argument from JSON: {}.".format(spec))
         return exp
 
+    def _register_if_needed(self, run_object):
+        """Registers Trainable or Function at runtime.
+
+        Assumes already registered if run_object is a string. Does not
+        register lambdas because they could be part of variant generation.
+        Also, does not inspect interface of given run_object.
+
+        Arguments:
+            run_object (str|function|class): Trainable to run. If string,
+                assumes it is an ID and does not modify it. Otherwise,
+                returns a string corresponding to the run_object name.
+
+        Returns:
+            A string representing the trainable identifier.
+        """
+
+        if isinstance(run_object, six.string_types):
+            return run_object
+        elif isinstance(run_object, types.FunctionType):
+            if run_object.__name__ == "<lambda>":
+                print("Not auto-registering lambdas - resolving as variant.")
+                return run_object
+            else:
+                name = run_object.__name__
+                register_trainable(name, run_object)
+                return name
+        elif isinstance(run_object, type):
+            name = run_object.__name__
+            register_trainable(name, run_object)
+            return name
+        else:
+            raise TuneError("Improper 'run' - not string nor trainable.")
+
 
 def convert_to_experiment_list(experiments):
     """Produces a list of Experiment objects.