From 22113be04cc735da61897a24f5916c3f4d681f68 Mon Sep 17 00:00:00 2001 From: Richard Liaw Date: Thu, 8 Nov 2018 23:45:05 -0800 Subject: [PATCH] [tune] Annotated Example Page and showcase Tutorials (#3267) Adds an example page and link in codebase. Closes #2728. --- doc/source/index.rst | 1 + doc/source/tune-examples.rst | 62 +++++++++++++++++++++++++++++ doc/source/tune.rst | 5 ++- python/ray/tune/README.rst | 8 ++++ python/ray/tune/examples/README.rst | 58 ++++++++++++++++++++++++++- 5 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 doc/source/tune-examples.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 5268054b7..ca56625b2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -74,6 +74,7 @@ Ray comes with libraries that accelerate deep learning and reinforcement learnin tune-schedulers.rst tune-searchalg.rst tune-package-ref.rst + tune-examples.rst .. toctree:: :maxdepth: 1 diff --git a/doc/source/tune-examples.rst b/doc/source/tune-examples.rst new file mode 100644 index 000000000..e0af86bcb --- /dev/null +++ b/doc/source/tune-examples.rst @@ -0,0 +1,62 @@ +Tune Examples +============= + +.. Keep this in sync with ray/python/ray/tune/examples/README.rst + +In our repository, we provide a variety of examples for the various use cases and features of Tune. + +If any example is broken, or if you'd like to add an example to this page, feel free to raise an issue on our Github repository. + + +General Examples +---------------- + +- `async_hyperband_example `__: + Example of using a Trainable class with AsyncHyperBandScheduler. +- `hyperband_example `__: + Example of using a Trainable class with HyperBandScheduler. Also uses the Experiment class API for specifying the experiment configuration. +- `hyperopt_example `__: + Optimizes a basic function using the function-based API and the HyperOptSearch (SearchAlgorithm wrapper for HyperOpt TPE). + Also uses the AsyncHyperBandScheduler. +- `pbt_example `__: + Example of using a Trainable class with PopulationBasedTraining scheduler. +- `pbt_ppo_example `__: + Example of optimizing a distributed RLlib algorithm (PPO) with the PopulationBasedTraining scheduler. + + +Keras Examples +-------------- + +- `tune_mnist_keras `__: + Converts the Keras MNIST example to use Tune with the function-based API and a Keras callback. Also shows how to easily convert something relying on argparse to use Tune. + + +PyTorch Examples +---------------- + +- `mnist_pytorch `__: + Converts the PyTorch MNIST example to use Tune with the function-based API. Also shows how to easily convert something relying on argparse to use Tune. +- `mnist_pytorch_trainable `__: + Converts the PyTorch MNIST example to use Tune with Trainable API. Also uses the HyperBandScheduler and checkpoints the model at the end. + + +TensorFlow Examples +------------------- + +- `tune_mnist_ray `__: + A basic example of tuning a TensorFlow model on MNIST using the Trainable class. +- `tune_mnist_ray_hyperband `__: + A basic example of tuning a TensorFlow model on MNIST using the Trainable class and the HyperBand scheduler. +- `tune_mnist_async_hyperband `__: + Example of tuning a TensorFlow model on MNIST using AsyncHyperBand. + + +Contributed Examples +-------------------- + +- `pbt_tune_cifar10_with_keras `__: + A contributed example of tuning a Keras model on CIFAR10 with the PopulationBasedTraining scheduler. +- `genetic_example `__: + Optimizing the michalewicz function using the contributed GeneticSearch search algorithm with AsyncHyperBandScheduler. + + diff --git a/doc/source/tune.rst b/doc/source/tune.rst index a849f3b81..87f28531b 100644 --- a/doc/source/tune.rst +++ b/doc/source/tune.rst @@ -7,7 +7,10 @@ Tune: Scalable Hyperparameter Search Tune is a scalable framework for hyperparameter search with a focus on deep learning and deep reinforcement learning. -You can find the code for Tune `here on GitHub `__. +You can find the code for Tune `here on GitHub `__. To get started with Tune, try going through `our tutorial of using Tune with Keras `__. + +(Experimental): You can try out `the above tutorial on a free hosted server via Binder `__. + Features -------- diff --git a/python/ray/tune/README.rst b/python/ray/tune/README.rst index 2d7533f56..5635ab3ff 100644 --- a/python/ray/tune/README.rst +++ b/python/ray/tune/README.rst @@ -6,6 +6,14 @@ Tune is a scalable framework for hyperparameter search with a focus on deep lear User documentation can be `found here `__. +Tutorial +-------- + +To get started with Tune, try going through `our tutorial of using Tune with Keras `__. + +(Experimental): You can try out `the above tutorial on a free hosted server via Binder `__. + + Citing Tune ----------- diff --git a/python/ray/tune/examples/README.rst b/python/ray/tune/examples/README.rst index 3d35497c8..a762a0570 100644 --- a/python/ray/tune/examples/README.rst +++ b/python/ray/tune/examples/README.rst @@ -1,4 +1,60 @@ Tune Examples ============= -Code examples for various schedulers and Tune features. +.. Keep this in sync with ray/doc/tune-examples.rst + +In our repository, we provide a variety of examples for the various use cases and features of Tune. + +If any example is broken, or if you'd like to add an example to this page, feel free to raise an issue on our Github repository. + + +General Examples +---------------- + +- `async_hyperband_example `__: + Example of using a Trainable class with AsyncHyperBandScheduler. +- `hyperband_example `__: + Example of using a Trainable class with HyperBandScheduler. Also uses the Experiment class API for specifying the experiment configuration. +- `hyperopt_example `__: + Optimizes a basic function using the function-based API and the HyperOptSearch (SearchAlgorithm wrapper for HyperOpt TPE). + Also uses the AsyncHyperBandScheduler. +- `pbt_example `__: + Example of using a Trainable class with PopulationBasedTraining scheduler. +- `pbt_ppo_example `__: + Example of optimizing a distributed RLlib algorithm (PPO) with the PopulationBasedTraining scheduler. + + +Keras Examples +-------------- + +- `tune_mnist_keras `__: + Converts the Keras MNIST example to use Tune with the function-based API and a Keras callback. Also shows how to easily convert something relying on argparse to use Tune. + + +PyTorch Examples +---------------- + +- `mnist_pytorch `__: + Converts the PyTorch MNIST example to use Tune with the function-based API. Also shows how to easily convert something relying on argparse to use Tune. +- `mnist_pytorch_trainable `__: + Converts the PyTorch MNIST example to use Tune with Trainable API. Also uses the HyperBandScheduler and checkpoints the model at the end. + + +TensorFlow Examples +------------------- + +- `tune_mnist_ray `__: + A basic example of tuning a TensorFlow model on MNIST using the Trainable class. +- `tune_mnist_ray_hyperband `__: + A basic example of tuning a TensorFlow model on MNIST using the Trainable class and the HyperBand scheduler. +- `tune_mnist_async_hyperband `__: + Example of tuning a TensorFlow model on MNIST using AsyncHyperBand. + + +Contributed Examples +-------------------- + +- `pbt_tune_cifar10_with_keras `__: + A contributed example of tuning a Keras model on CIFAR10 with the PopulationBasedTraining scheduler. +- `genetic_example `__: + Optimizing the michalewicz function using the contributed GeneticSearch search algorithm with AsyncHyperBandScheduler.