[air/tuner/docs] Update docs for Tuner() API 1: RSTs, docs, move reus…

…e_actors (ray-project#26930) Signed-off-by: Kai Fricke [email protected] Why are these changes needed? Splitting up ray-project#26884: This PR includes changes to use Tuner() instead of tune.run() for most docs files (rst and py), and a change to move reuse_actors to the TuneConfig Signed-off-by: klwuibm <[email protected]>
yuanchi2807 · Jul 27, 2022 · c1a6729 · c1a6729
1 parent 25a0a01
commit c1a6729
Show file tree

Hide file tree

Showing 39 changed files with 629 additions and 443 deletions.
diff --git a/README.rst b/README.rst
@@ -135,17 +135,19 @@ This example runs a parallel grid search to optimize an example objective functi
  session.report({"mean_loss": intermediate_score})
 
 
- analysis = tune.run(
+ tuner = tune.Tuner(
  training_function,
- config={
+ param_space={
  "alpha": tune.grid_search([0.001, 0.01, 0.1]),
  "beta": tune.choice([1, 2, 3])
  })
+ 
+ results = tuner.fit()
 
- print("Best config: ", analysis.get_best_config(metric="mean_loss", mode="min"))
+ print("Best config: ", results.get_best_result(metric="mean_loss", mode="min").config)
 
  # Get a dataframe for analyzing trial results.
- df = analysis.results_df
+ df = results.get_dataframe()
 
 If TensorBoard is installed, automatically visualize all trial results:
 

diff --git a/doc/source/data/doc_code/key_concepts.py b/doc/source/data/doc_code/key_concepts.py
@@ -15,7 +15,14 @@ def objective(*args):
 # By setting `max_concurrent_trials=3`, this ensures the cluster will always
 # have a sparse CPU for Datasets. Try setting `max_concurrent_trials=4` here,
 # and notice that the experiment will appear to hang.
-tune.run(objective, num_samples=4, max_concurrent_trials=3)
+tuner = tune.Tuner(
+ tune.with_resources(objective, {"cpu": 1}),
+ tune_config=tune.TuneConfig(
+ num_samples=1,
+ max_concurrent_trials=3
+ )
+)
+tuner.fit()
 # __resource_allocation_1_end__
 # fmt: on
 
@@ -33,14 +40,14 @@ def objective(*args):
 
 # This runs smoothly since _max_cpu_fraction_per_node is set to 0.8, effectively
 # reserving 1 CPU for Datasets task execution.
-tune.run(
- objective,
- num_samples=4,
- resources_per_trial=tune.PlacementGroupFactory(
+tuner = tune.Tuner(
+ tune.with_resources(objective, tune.PlacementGroupFactory(
  [{"CPU": 1}],
  _max_cpu_fraction_per_node=0.8,
- ),
+ )),
+ tune_config=tune.TuneConfig(num_samples=1)
 )
+tuner.fit()
 # __resource_allocation_2_end__
 # fmt: on
 

diff --git a/doc/source/ray-core/examples/dask_xgboost/dask_xgboost.ipynb b/doc/source/ray-core/examples/dask_xgboost/dask_xgboost.ipynb
@@ -61,7 +61,7 @@
  "from xgboost_ray import RayDMatrix, RayParams, train, predict\n",
  "\n",
  "import ray\n",
- "from ray import tune\n",
+ "from ray import air, tune\n",
  "from ray.util.dask import ray_dask_get"
  ]
  },
@@ -351,7 +351,7 @@
  "and ``max_depth``. We are using [Tune's samplers to define the search\n",
  "space](https://docs.ray.io/en/latest/tune/user-guide.html#search-space-grid-random).\n",
  "\n",
- "The experiment configuration is done through ``tune.run``. We set the amount\n",
+ "The experiment configuration is done through ``Tuner()``. We set the amount\n",
  "of resources each trial (hyperparameter combination) requires by using the\n",
  "``get_tune_resources`` method of ``RayParams``. The ``num_samples`` argument\n",
  "controls how many trials will be ran in total. In the end, the best\n",
@@ -387,32 +387,39 @@
  " )\n",
  "\n",
  " tune_start_time = time.time()\n",
- "\n",
- " analysis = tune.run(\n",
- " tune.with_parameters(\n",
- " train_xgboost,\n",
- " train_df=train_df,\n",
- " test_df=test_df,\n",
- " target_column=target_column,\n",
- " ray_params=ray_params,\n",
+ " \n",
+ " tuner = tune.Tuner(\n",
+ " tune.with_resources(\n",
+ " tune.with_parameters(\n",
+ " train_xgboost,\n",
+ " train_df=train_df,\n",
+ " test_df=test_df,\n",
+ " target_column=target_column,\n",
+ " ray_params=ray_params,\n",
+ " ),\n",
+ " resources=ray_params.get_tune_resources()\n",
+ " ),\n",
+ " tune_config=tune.TuneConfig(\n",
+ " num_samples=10,\n",
+ " metric=\"eval-error\",\n",
+ " mode=\"min\",\n",
  " ),\n",
- " # Use the `get_tune_resources` helper function to set the resources.\n",
- " resources_per_trial=ray_params.get_tune_resources(),\n",
- " config=config,\n",
- " num_samples=10,\n",
- " metric=\"eval-error\",\n",
- " mode=\"min\",\n",
+ " param_space=config\n",
  " )\n",
+ " results = tuner.fit()\n",
+ " \n",
+ " best_result = results.get_best_result()\n",
+ "\n",
  "\n",
  " tune_end_time = time.time()\n",
  " tune_duration = tune_end_time - tune_start_time\n",
  " print(f\"Total time taken: {tune_duration} seconds.\")\n",
  "\n",
- " accuracy = 1.0 - analysis.best_result[\"eval-error\"]\n",
- " print(f\"Best model parameters: {analysis.best_config}\")\n",
+ " accuracy = 1.0 - best_result.metrics[\"eval-error\"]\n",
+ " print(f\"Best model parameters: {best_result.config}\")\n",
  " print(f\"Best model total accuracy: {accuracy:.4f}\")\n",
  "\n",
- " return analysis.best_config"
+ " return best_result.config"
  ]
  },
  {
@@ -470,9 +477,21 @@
  ],
  "metadata": {
  "kernelspec": {
- "display_name": "Python 3",
+ "display_name": "Python 3 (ipykernel)",
  "language": "python",
  "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.7.7"
  }
  },
  "nbformat": 4,

diff --git a/doc/source/ray-core/examples/dask_xgboost/dask_xgboost.py b/doc/source/ray-core/examples/dask_xgboost/dask_xgboost.py
@@ -251,7 +251,7 @@ def train_xgboost(config, train_df, test_df, target_column, ray_params):
 # and ``max_depth``. We are using [Tune's samplers to define the search
 # space](https://docs.ray.io/en/latest/tune/user-guide.html#search-space-grid-random).
 #
-# The experiment configuration is done through ``tune.run``. We set the amount
+# The experiment configuration is done through ``Tuner()``. We set the amount
 # of resources each trial (hyperparameter combination) requires by using the
 # ``get_tune_resources`` method of ``RayParams``. The ``num_samples`` argument
 # controls how many trials will be ran in total. In the end, the best
@@ -282,31 +282,36 @@ def tune_xgboost(train_df, test_df, target_column):
 
  tune_start_time = time.time()
 
- analysis = tune.run(
- tune.with_parameters(
- train_xgboost,
- train_df=train_df,
- test_df=test_df,
- target_column=target_column,
- ray_params=ray_params,
+ tuner = tune.Tuner(
+ tune.with_resources(
+ tune.with_parameters(
+ train_xgboost,
+ train_df=train_df,
+ test_df=test_df,
+ target_column=target_column,
+ ray_params=ray_params,
+ ),
+ resources=ray_params.get_tune_resources(),
  ),
- # Use the `get_tune_resources` helper function to set the resources.
- resources_per_trial=ray_params.get_tune_resources(),
- config=config,
- num_samples=10,
- metric="eval-error",
- mode="min",
+ tune_config=tune.TuneConfig(
+  num_samples=10,
+  metric="eval-error",
+  mode="min",
+ ),
+ param_space=config,
  )
+ results = tuner.fit()
 
  tune_end_time = time.time()
  tune_duration = tune_end_time - tune_start_time
  print(f"Total time taken: {tune_duration} seconds.")
 
- accuracy = 1.0 - analysis.best_result["eval-error"]
- print(f"Best model parameters: {analysis.best_config}")
+ best_result = results.get_best_result()
+ accuracy = 1.0 - best_result.metrics["eval-error"]
+ print(f"Best model parameters: {best_result.config}")
  print(f"Best model total accuracy: {accuracy:.4f}")
 
- return analysis.best_config
+ return best_result.config
 
 
 # Hyperparameter optimization may take some time to complete.

diff --git a/doc/source/ray-core/examples/using-ray-with-pytorch-lightning.rst b/doc/source/ray-core/examples/using-ray-with-pytorch-lightning.rst
@@ -101,6 +101,7 @@ To report metrics back to Tune after each validation epoch, we can use the ``Tun
 
 .. code-block:: python
 
+ from ray import air, tune
  from ray.tune.integration.pytorch_lightning import TuneReportCallback
 
  def train_mnist(config):
@@ -123,15 +124,20 @@ To report metrics back to Tune after each validation epoch, we can use the ``Tun
  }
 
  # Make sure to specify how many actors each training run will create via the "extra_cpu" field.
- analysis = tune.run(
- train_mnist,
+ tuner = tune.Tuner(
+ train_mnist,
+ tune_config=tune.TuneConfig(
  metric="loss",
  mode="min",
- config=config,
- num_samples=num_samples,
- name="tune_mnist")
+ num_samples=num_samples
+ ),
+ param_space=config,
+ run_config=air.RunConfig(name="tune_mnist"),
+ )
+ 
+ results = tuner.fit()
 
- print("Best hyperparameters found were: ", analysis.best_config)
+ print("Best hyperparameters found were: ", results.get_best_result().config)
 
 
 And if you want to add periodic checkpointing as well, you can use the ``TuneReportCheckpointCallback`` instead.
@@ -155,14 +161,15 @@ In this case, you want to use the `Ray Lightning Library's <https://github.com/r
 
 With this integration, you can run multiple PyTorch Lightning training runs in parallel,
 each with a different hyperparameter configuration, and each training run also parallelized.
-All you have to do is move your training code to a function, pass the function to ``tune.run``, and make sure to add the appropriate callback (Either ``TuneReportCallback`` or ``TuneReportCheckpointCallback``) to your PyTorch Lightning Trainer.
+All you have to do is move your training code to a function, pass the function to ``Tuner()``, and make sure to add the appropriate callback (Either ``TuneReportCallback`` or ``TuneReportCheckpointCallback``) to your PyTorch Lightning Trainer.
 
 .. warning:: Make sure to use the callbacks from the Ray Lightning library and not the one from the Tune library, i.e. use ``ray_lightning.tune.TuneReportCallback`` and not ``ray.tune.integrations.pytorch_lightning.TuneReportCallback``.
 
 Example using Ray Lightning with Tune:
 
 .. code-block:: python
 
+ from ray import air, tune
  from ray_lightning import RayPlugin
  from ray_lightning.tune import TuneReportCallback
 
@@ -189,16 +196,16 @@ Example using Ray Lightning with Tune:
  }
 
  # Make sure to specify how many actors each training run will create via the "extra_cpu" field.
- analysis = tune.run(
- train_mnist,
+ tuner = tune.Tuner(
+ tune.with_resources(train_mnist, {"cpu": 1, "extra_cpu": 4}),
+ tune_config=tune.TuneConfig(
  metric="loss",
  mode="min",
- config=config,
  num_samples=num_samples,
-  resources_per_trial={
-  "cpu": 1,
-  "extra_cpu": 4
-  },
-  name="tune_mnist")
+ ),
+ param_space=config
+ )
+ 
+ results = tuner.fit()
 
- print("Best hyperparameters found were: ", analysis.best_config)
+ print("Best hyperparameters found were: ", results.get_best_result().config)
diff --git a/doc/source/ray-core/gotchas.rst b/doc/source/ray-core/gotchas.rst
@@ -95,22 +95,27 @@ of Ray Tasks itself, e.g.
 
 .. code-block:: python
 
+ from ray import air, tune
+
  def create_task_that_uses_resources():
  @ray.remote(num_cpus=10)
  def sample_task():
  print("Hello")
  return
 
- return ray.get([my_task.remote() for i in range(10)])
+ return ray.get([sample_task.remote() for i in range(10)])
 
  def objective(config):
  create_task_that_uses_resources()
 
- analysis = tune.run(objective, config=search_space)
+ tuner = tune.Tuner(objective, param_space={"a": 1})
+ tuner.fit()
 
-This will hang forever. 
+This will error with message: 
+ValueError: Cannot schedule create_task_that_uses_resources.<locals>.sample_task with the placement group 
+because the resource request {'CPU': 10} cannot fit into any bundles for the placement group, [{'CPU': 1.0}].
 
-**Expected behavior**: The above executes and doesn't hang.
+**Expected behavior**: The above executes.
 
 **Fix**: In the ``@ray.remote`` declaration of tasks
 called by ``create_task_that_uses_resources()`` , include a

diff --git a/doc/source/ray-overview/doc_test/ray_rllib.py b/doc/source/ray-overview/doc_test/ray_rllib.py
@@ -1,8 +1,11 @@
-from ray import tune
+from ray import air, tune
 from ray.rllib.algorithms.ppo import PPO
 
-tune.run(
+tuner = tune.Tuner(
  PPO,
- stop={"episode_len_mean": 20},
- config={"env": "CartPole-v0", "framework": "torch", "log_level": "INFO"},
+ run_config=air.RunConfig(
+ stop={"episode_len_mean": 20},
+ ),
+ param_space={"env": "CartPole-v0", "framework": "torch", "log_level": "INFO"},
 )
+tuner.fit()
diff --git a/doc/source/ray-overview/doc_test/ray_tune.py b/doc/source/ray-overview/doc_test/ray_tune.py
@@ -16,15 +16,17 @@ def training_function(config):
  session.report({"mean_loss": intermediate_score})
 
 
-analysis = tune.run(
+tuner = tune.Tuner(
  training_function,
- config={
+ param_space={
  "alpha": tune.grid_search([0.001, 0.01, 0.1]),
  "beta": tune.choice([1, 2, 3]),
  },
 )
+results = tuner.fit()
 
-print("Best config: ", analysis.get_best_config(metric="mean_loss", mode="min"))
+best_result = results.get_best_result(metric="mean_loss", mode="min")
+print("Best result: ", best_result.metrics)
 
 # Get a dataframe for analyzing trial results.
-df = analysis.results_df
+df = results.get_dataframe()
diff --git a/doc/source/rllib/core-concepts.rst b/doc/source/rllib/core-concepts.rst
@@ -85,13 +85,13 @@ which implements the proximal policy optimization algorithm in RLlib.
  from ray import tune
 
  # Configure.
- from ray.rllib.algorithms import PPOConfig
- config = PPOConfig().environment("CartPole-v0").training(train_batch_size=4000)
+ from ray.rllib.algorithms.ppo import PPO, PPOConfig
+ config = PPOConfig().environment(env="CartPole-v0").training(train_batch_size=4000)
 
  # Train via Ray Tune.
  # Note that Ray Tune does not yet support AlgorithmConfig objects, hence
  # we need to convert back to old-style config dicts.
- tune.run("PPO", config=config.to_dict())
+ tune.run(PPO, param_space=config.to_dict())
 
 
 .. tabbed:: RLlib Command Line

diff --git a/doc/source/train/user_guide.rst b/doc/source/train/user_guide.rst
@@ -1217,8 +1217,10 @@ Reproducibility
  # Convert this to a trainable.
  trainable = trainer.to_tune_trainable(training_func, dataset=dataset)
 
- analysis = tune.run(trainable, config={
- "lr": tune.uniform(), "batch_size": tune.randint(1, 2, 3)}, num_samples=12)
+ tuner = tune.Tuner(trainable,
+ param_space={"lr": tune.uniform(), "batch_size": tune.randint(1, 2, 3)},
+ tune_config=tune.TuneConfig(num_samples=12))
+ results = tuner.fit()
 ..
  Advanced APIs
  -------------