[tune] resources_per_trial from trial_resources (#3580)

Renaming variable due to user errors.

python/ray/tune/experiment.py

@@ -15,6 +15,23 @@ from ray.tune.result import DEFAULT_RESULTS_DIR
 logger = logging.getLogger(__name__)
 
 
+def _raise_deprecation_note(deprecated, replacement, soft=False):
+    """User notification for deprecated parameter.
+
+    Arguments:
+        deprecated (str): Deprecated parameter.
+        replacement (str): Replacement parameter to use instead.
+        soft (bool): Fatal if True.
+    """
+    error_msg = ("`{deprecated}` is deprecated. Please use `{replacement}`. "
+                 "`{deprecated}` will be removed in future versions of "
+                 "Ray.".format(deprecated=deprecated, replacement=replacement))
+    if soft:
+        logger.warning(error_msg)
+    else:
+        raise DeprecationWarning(error_msg)
+
+
 class Experiment(object):
     """Tracks experiment specifications.
 
@@ -31,12 +48,10 @@ class Experiment(object):
         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,
+        resources_per_trial (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 in ``Trainable.default_resource_request()``.
-        repeat (int): Deprecated and will be removed in future versions of
-            Ray. Use `num_samples` instead.
         num_samples (int): Number of times to sample from the
             hyperparameter space. Defaults to 1. If `grid_search` is
             provided as an argument, the grid will be repeated
@@ -62,6 +77,10 @@ class Experiment(object):
             checkpointing is enabled. Defaults to 3.
         restore (str): Path to checkpoint. Only makes sense to set if
             running 1 trial. Defaults to None.
+        repeat: Deprecated and will be removed in future versions of
+            Ray. Use `num_samples` instead.
+        trial_resources: Deprecated and will be removed in future versions of
+            Ray. Use `resources_per_trial` instead.
 
 
     Examples:
@@ -73,7 +92,7 @@ class Experiment(object):
         >>>         "alpha": tune.grid_search([0.2, 0.4, 0.6]),
         >>>         "beta": tune.grid_search([1, 2]),
         >>>     },
-        >>>     trial_resources={
+        >>>     resources_per_trial={
         >>>         "cpu": 1,
         >>>         "gpu": 0
         >>>     },
@@ -90,8 +109,7 @@ class Experiment(object):
                  run,
                  stop=None,
                  config=None,
-                 trial_resources=None,
-                 repeat=1,
+                 resources_per_trial=None,
                  num_samples=1,
                  local_dir=None,
                  upload_dir=None,
@@ -101,15 +119,25 @@ class Experiment(object):
                  checkpoint_freq=0,
                  checkpoint_at_end=False,
                  max_failures=3,
-                 restore=None):
+                 restore=None,
+                 repeat=None,
+                 trial_resources=None):
         validate_sync_function(sync_function)
         if sync_function:
             assert upload_dir, "Need `upload_dir` if sync_function given."
+
+        if repeat:
+            _raise_deprecation_note("repeat", "num_samples", soft=False)
+        if trial_resources:
+            _raise_deprecation_note(
+                "trial_resources", "resources_per_trial", soft=True)
+            resources_per_trial = trial_resources
+
         spec = {
             "run": self._register_if_needed(run),
             "stop": stop or {},
             "config": config or {},
-            "trial_resources": trial_resources,
+            "resources_per_trial": resources_per_trial,
             "num_samples": num_samples,
             "local_dir": local_dir or DEFAULT_RESULTS_DIR,
             "upload_dir": upload_dir or "",  # argparse converts None to "null"
@@ -136,13 +164,6 @@ class Experiment(object):
         if "run" not in spec:
             raise TuneError("No trainable specified!")
 
-        if "repeat" in spec:
-            raise DeprecationWarning("The parameter `repeat` is deprecated; \
-                converting to `num_samples`. `repeat` will be removed in \
-                future versions of Ray.")
-            spec["num_samples"] = spec["repeat"]
-            del spec["repeat"]
-
         # Special case the `env` param for RLlib by automatically
         # moving it into the `config` section.
         if "env" in spec: