From d85274a12e73a59a2f67c813cf6fb9fc83c9cc06 Mon Sep 17 00:00:00 2001 From: Eric Liang Date: Thu, 8 Mar 2018 09:18:09 -0800 Subject: [PATCH] [docs] update to expose libraries + landing page (#1642) --- doc/source/example-hyperopt.rst | 245 --------------------- doc/source/hyperband.rst | 99 +++++++++ doc/source/images/hyperband_allocation.png | Bin 0 -> 32218 bytes doc/source/images/hyperband_bracket.png | Bin 0 -> 25997 bytes doc/source/images/hyperband_eta.png | Bin 0 -> 35238 bytes doc/source/index.rst | 61 +++-- doc/source/pbt.rst | 33 +++ doc/source/tune-api.svg | 4 + doc/source/tune.rst | 73 +----- 9 files changed, 183 insertions(+), 332 deletions(-) delete mode 100644 doc/source/example-hyperopt.rst create mode 100644 doc/source/hyperband.rst create mode 100644 doc/source/images/hyperband_allocation.png create mode 100644 doc/source/images/hyperband_bracket.png create mode 100644 doc/source/images/hyperband_eta.png create mode 100644 doc/source/pbt.rst create mode 100644 doc/source/tune-api.svg diff --git a/doc/source/example-hyperopt.rst b/doc/source/example-hyperopt.rst deleted file mode 100644 index ff32bffa0..000000000 --- a/doc/source/example-hyperopt.rst +++ /dev/null @@ -1,245 +0,0 @@ -Hyperparameter Optimization -=========================== - -This document provides a walkthrough of the hyperparameter optimization example. - -.. note:: - - To learn about Ray's built-in hyperparameter optimization framework, see `Ray Tune `__. - -To run the application, first install some dependencies. - -.. code-block:: bash - - pip install tensorflow - -You can view the `code for this example`_. - -.. _`code for this example`: https://github.com/ray-project/ray/tree/master/examples/hyperopt - -The simple script that processes results as they become available and launches -new experiments can be run as follows. - -.. code-block:: bash - - python ray/examples/hyperopt/hyperopt_simple.py --trials=5 --steps=10 - -The variant that divides training into multiple segments and aggressively -terminates poorly performing models can be run as follows. - -.. code-block:: bash - - python ray/examples/hyperopt/hyperopt_adaptive.py --num-starting-segments=5 \ - --num-segments=10 \ - --steps-per-segment=20 - -Machine learning algorithms often have a number of *hyperparameters* whose -values must be chosen by the practitioner. For example, an optimization -algorithm may have a step size, a decay rate, and a regularization coefficient. -In a deep network, the network parameterization itself (e.g., the number of -layers and the number of units per layer) can be considered a hyperparameter. - -Choosing these parameters can be challenging, and so a common practice is to -search over the space of hyperparameters. One approach that works surprisingly -well is to randomly sample different options. - -Problem Setup -------------- - -Suppose that we want to train a convolutional network, but we aren't sure how to -choose the following hyperparameters: - -- the learning rate -- the batch size -- the dropout probability -- the standard deviation of the distribution from which to initialize the - network weights - -Suppose that we've defined a remote function ``train_cnn_and_compute_accuracy``, -which takes values for these hyperparameters as its input (along with the -dataset), trains a convolutional network using those hyperparameters, and -returns the accuracy of the trained model on a validation set. - -.. code-block:: python - - import numpy as np - import ray - - @ray.remote - def train_cnn_and_compute_accuracy(hyperparameters, - train_images, - train_labels, - validation_images, - validation_labels): - # Construct a deep network, train it, and return the accuracy on the - # validation data. - return np.random.uniform(0, 1) - -Basic random search -------------------- - -Something that works surprisingly well is to try random values for the -hyperparameters. For example, we can write a function that randomly generates -hyperparameter configurations. - -.. code-block:: python - - def generate_hyperparameters(): - # Randomly choose values for the hyperparameters. - return {"learning_rate": 10 ** np.random.uniform(-5, 5), - "batch_size": np.random.randint(1, 100), - "dropout": np.random.uniform(0, 1), - "stddev": 10 ** np.random.uniform(-5, 5)} - -In addition, let's assume that we've started Ray and loaded some data. - -.. code-block:: python - - import ray - - ray.init() - - from tensorflow.examples.tutorials.mnist import input_data - mnist = input_data.read_data_sets("MNIST_data", one_hot=True) - train_images = ray.put(mnist.train.images) - train_labels = ray.put(mnist.train.labels) - validation_images = ray.put(mnist.validation.images) - validation_labels = ray.put(mnist.validation.labels) - - -Then basic random hyperparameter search looks something like this. We launch a -bunch of experiments, and we get the results. - -.. code-block:: python - - # Generate a bunch of hyperparameter configurations. - hyperparameter_configurations = [generate_hyperparameters() for _ in range(20)] - - # Launch some experiments. - results = [] - for hyperparameters in hyperparameter_configurations: - results.append(train_cnn_and_compute_accuracy.remote(hyperparameters, - train_images, - train_labels, - validation_images, - validation_labels)) - - # Get the results. - accuracies = ray.get(results) - -Then we can inspect the contents of `accuracies` and see which set of -hyperparameters worked the best. Note that in the above example, the for loop -will run instantaneously and the program will block in the call to ``ray.get``, -which will wait until all of the experiments have finished. - -Processing results as they become available -------------------------------------------- - -One problem with the above approach is that you have to wait for all of the -experiments to finish before you can process the results. Instead, you may want -to process the results as they become available, perhaps in order to adaptively -choose new experiments to run, or perhaps simply so you know how well the -experiments are doing. To process the results as they become available, we can -use the ``ray.wait`` primitive. - -The most simple usage is the following. This example is implemented in more -detail in driver.py_. - -.. code-block:: python - - # Launch some experiments. - remaining_ids = [] - for hyperparameters in hyperparameter_configurations: - remaining_ids.append(train_cnn_and_compute_accuracy.remote(hyperparameters, - train_images, - train_labels, - validation_images, - validation_labels)) - - # Whenever a new experiment finishes, print the value and start a new - # experiment. - for i in range(100): - ready_ids, remaining_ids = ray.wait(remaining_ids, num_returns=1) - accuracy = ray.get(ready_ids[0]) - print("Accuracy is {}".format(accuracy)) - # Start a new experiment. - new_hyperparameters = generate_hyperparameters() - remaining_ids.append(train_cnn_and_compute_accuracy.remote(new_hyperparameters, - train_images, - train_labels, - validation_images, - validation_labels)) - -.. _driver.py: https://github.com/ray-project/ray/blob/master/examples/hyperopt/driver.py - -More sophisticated hyperparameter search ----------------------------------------- - -Hyperparameter search algorithms can get much more sophisticated. So far, we've -been treating the function ``train_cnn_and_compute_accuracy`` as a black box, -that we can choose its inputs and inspect its outputs, but once we decide to run -it, we have to run it until it finishes. - -However, there is often more structure to be exploited. For example, if the -training procedure is going poorly, we can end the session early and invest more -resources in the more promising hyperparameter experiments. And if we've saved -the state of the training procedure, we can always restart it again later. - -This is one of the ideas of the Hyperband_ algorithm. Start with a huge number -of hyperparameter configurations, aggressively stop the bad ones, and invest -more resources in the promising experiments. - -To implement this, we can first adapt our training method to optionally take a -model and to return the updated model. - -.. code-block:: python - - @ray.remote - def train_cnn_and_compute_accuracy(hyperparameters, model=None): - # Construct a deep network, train it, and return the accuracy on the - # validation data as well as the latest version of the model. If the model - # argument is not None, this will continue training an existing model. - validation_accuracy = np.random.uniform(0, 1) - new_model = model - return validation_accuracy, new_model - -Here's a different variant that uses the same principles. Divide each training -session into a series of shorter training sessions. Whenever a short session -finishes, if it still looks promising, then continue running it. If it isn't -doing well, then terminate it and start a new experiment. - -.. code-block:: python - - import numpy as np - - def is_promising(model): - # Return true if the model is doing well and false otherwise. In practice, - # this function will want more information than just the model. - return np.random.choice([True, False]) - - # Start 10 experiments. - remaining_ids = [] - for _ in range(10): - experiment_id = train_cnn_and_compute_accuracy.remote(hyperparameters, model=None) - remaining_ids.append(experiment_id) - - accuracies = [] - for i in range(100): - # Whenever a segment of an experiment finishes, decide if it looks promising - # or not. - ready_ids, remaining_ids = ray.wait(remaining_ids, num_returns=1) - experiment_id = ready_ids[0] - current_accuracy, current_model = ray.get(experiment_id) - accuracies.append(current_accuracy) - - if is_promising(experiment_id): - # Continue running the experiment. - experiment_id = train_cnn_and_compute_accuracy.remote(hyperparameters, - model=current_model) - else: - # Start a new experiment. - experiment_id = train_cnn_and_compute_accuracy.remote(hyperparameters) - - remaining_ids.append(experiment_id) - -.. _Hyperband: https://arxiv.org/abs/1603.06560 diff --git a/doc/source/hyperband.rst b/doc/source/hyperband.rst new file mode 100644 index 000000000..1b3c7bf4d --- /dev/null +++ b/doc/source/hyperband.rst @@ -0,0 +1,99 @@ +HyperBand and Early Stopping +============================ + +Ray Tune includes distributed implementations of early stopping algorithms such as `Median Stopping Rule `__, `HyperBand `__, and an `asynchronous version of HyperBand `__. These algorithms are very resource efficient and can outperform Bayesian Optimization methods in `many cases `__. + +Asynchronous HyperBand +---------------------- + +The `asynchronous version of HyperBand `__ scheduler can be plugged in on top of an existing grid or random search. This can be done by setting the ``scheduler`` parameter of ``run_experiments``, e.g. + +.. code-block:: python + + run_experiments({...}, scheduler=AsyncHyperBandScheduler()) + +Compared to the original version of HyperBand, this implementation provides better parallelism and avoids straggler issues during eliminations. An example of this can be found in `async_hyperband_example.py `__. **We recommend using this over the standard HyperBand scheduler.** + +.. autoclass:: ray.tune.async_hyperband.AsyncHyperBandScheduler + +HyperBand +--------- + +.. note:: Note that the HyperBand scheduler requires your trainable to support checkpointing, which is described in `Ray Tune documentation `__. Checkpointing enables the scheduler to multiplex many concurrent trials onto a limited size cluster. + +Ray Tune also implements the `standard version of HyperBand `__. You can use it as such: + +.. code-block:: python + + run_experiments({...}, scheduler=HyperBandScheduler()) + +An example of this can be found in `hyperband_example.py `__. The progress of one such HyperBand run is shown below. + + +:: + + == Status == + Using HyperBand: num_stopped=0 total_brackets=5 + Round #0: + Bracket(n=5, r=100, completed=80%): {'PAUSED': 4, 'PENDING': 1} + Bracket(n=8, r=33, completed=23%): {'PAUSED': 4, 'PENDING': 4} + Bracket(n=15, r=11, completed=4%): {'RUNNING': 2, 'PAUSED': 2, 'PENDING': 11} + Bracket(n=34, r=3, completed=0%): {'RUNNING': 2, 'PENDING': 32} + Bracket(n=81, r=1, completed=0%): {'PENDING': 38} + Resources used: 4/4 CPUs, 0/0 GPUs + Result logdir: ~/ray_results/hyperband_test + PAUSED trials: + - my_class_0_height=99,width=43: PAUSED [pid=11664], 0 s, 100 ts, 97.1 rew + - my_class_11_height=85,width=81: PAUSED [pid=11771], 0 s, 33 ts, 32.8 rew + - my_class_12_height=0,width=52: PAUSED [pid=11785], 0 s, 33 ts, 0 rew + - my_class_19_height=44,width=88: PAUSED [pid=11811], 0 s, 11 ts, 5.47 rew + - my_class_27_height=96,width=84: PAUSED [pid=11840], 0 s, 11 ts, 12.5 rew + ... 5 more not shown + PENDING trials: + - my_class_10_height=12,width=25: PENDING + - my_class_13_height=90,width=45: PENDING + - my_class_14_height=69,width=45: PENDING + - my_class_15_height=41,width=11: PENDING + - my_class_16_height=57,width=69: PENDING + ... 81 more not shown + RUNNING trials: + - my_class_23_height=75,width=51: RUNNING [pid=11843], 0 s, 1 ts, 1.47 rew + - my_class_26_height=16,width=48: RUNNING + - my_class_31_height=40,width=10: RUNNING + - my_class_53_height=28,width=96: RUNNING + +.. autoclass:: ray.tune.hyperband.HyperBandScheduler + + +HyperBand Implementation Details +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementation details may deviate slightly from theory but are focused on increasing usability. Note: ``R``, ``s_max``, and ``eta`` are parameters of HyperBand given by the paper. See `this post `_ for context. + +1. Both ``s_max`` (representing the ``number of brackets - 1``) and ``eta``, representing the downsampling rate, are fixed. In many practical settings, ``R``, which represents some resource unit and often the number of training iterations, can be set reasonably large, like ``R >= 200``. For simplicity, assume ``eta = 3``. Varying ``R`` between ``R = 200`` and ``R = 1000`` creates a huge range of the number of trials needed to fill up all brackets. + +.. image:: images/hyperband_bracket.png + +On the other hand, holding ``R`` constant at ``R = 300`` and varying ``eta`` also leads to HyperBand configurations that are not very intuitive: + +.. image:: images/hyperband_eta.png + +The implementation takes the same configuration as the example given in the paper and exposes ``max_t``, which is not a parameter in the paper. + +2. The example in the `post `_ to calculate ``n_0`` is actually a little different than the algorithm given in the paper. In this implementation, we implement ``n_0`` according to the paper (which is `n` in the below example): + +.. image:: images/hyperband_allocation.png + + +3. There are also implementation specific details like how trials are placed into brackets which are not covered in the paper. This implementation places trials within brackets according to smaller bracket first - meaning that with low number of trials, there will be less early stopping. + +Median Stopping Rule +-------------------- + +The Median Stopping Rule implements the simple strategy of stopping a trial if its performance falls below the median of other trials at similar points in time. You can set the ``scheduler`` parameter as such: + +.. code-block:: python + + run_experiments({...}, scheduler=MedianStoppingRule()) + +.. autoclass:: ray.tune.median_stopping_rule.MedianStoppingRule diff --git a/doc/source/images/hyperband_allocation.png b/doc/source/images/hyperband_allocation.png new file mode 100644 index 0000000000000000000000000000000000000000..7df0de7664fc540c4f8395badcc19c14a8e4ed39 GIT binary patch literal 32218 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 literal 0 HcmV?d00001 diff --git a/doc/source/images/hyperband_bracket.png b/doc/source/images/hyperband_bracket.png new file mode 100644 index 0000000000000000000000000000000000000000..0aac889b18c589df627c44ba2a7649a94d01150a GIT binary patch literal 25997 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 RAZSB0JuRGOnYwNG{{gDu>X85d literal 0 HcmV?d00001 diff --git a/doc/source/images/hyperband_eta.png b/doc/source/images/hyperband_eta.png new file mode 100644 index 0000000000000000000000000000000000000000..1353cc9c2e2874dadeed1aa70d66180d88f50a58 GIT binary patch literal 35238 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 literal 0 HcmV?d00001 diff --git a/doc/source/index.rst b/doc/source/index.rst index b705a997e..ec5f30037 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,6 +9,31 @@ Ray *Ray is a flexible, high-performance distributed execution framework.* + +Ray is easy to install: ``pip install ray`` + +Example Use +----------- + ++------------------------------------------------+----------------------------------------------------+ +| **Basic Python** | **Distributed with Ray** | ++------------------------------------------------+----------------------------------------------------+ +|.. code-block:: python |.. code-block:: python | +| | | +| # Execute f serially. | # Execute f in parallel. | +| | | +| | @ray.remote | +| def f(): | def f(): | +| time.sleep(1) | time.sleep(1) | +| return 1 | return 1 | +| | | +| | | +| | ray.init() | +| results = [f() for i in range(4)] | results = ray.get([f.remote() for i in range(4)]) | ++------------------------------------------------+----------------------------------------------------+ + + + View the `codebase on GitHub`_. .. _`codebase on GitHub`: https://github.com/ray-project/ray @@ -21,27 +46,6 @@ Ray comes with libraries that accelerate deep learning and reinforcement learnin .. _`Ray Tune`: tune.html .. _`Ray RLlib`: rllib.html -Example Program ---------------- - -+------------------------------------------------+----------------------------------------------------+ -| **Basic Python** | **Distributed with Ray** | -+------------------------------------------------+----------------------------------------------------+ -|.. code:: python |.. code-block:: python | -| | | -| import time | import time | -| | import ray | -| | | -| | ray.init() | -| | | -| | @ray.remote | -| def f(): | def f(): | -| time.sleep(1) | time.sleep(1) | -| return 1 | return 1 | -| | | -| # Execute f serially. | # Execute f in parallel. | -| results = [f() for i in range(4)] | results = ray.get([f.remote() for i in range(4)]) | -+------------------------------------------------+----------------------------------------------------+ .. toctree:: :maxdepth: 1 @@ -60,16 +64,27 @@ Example Program api.rst actors.rst using-ray-with-gpus.rst + webui.rst + +.. toctree:: + :maxdepth: 1 + :caption: Ray Tune + tune.rst + hyperband.rst + pbt.rst + +.. toctree:: + :maxdepth: 1 + :caption: Ray RLlib + rllib.rst rllib-dev.rst - webui.rst .. toctree:: :maxdepth: 1 :caption: Examples - example-hyperopt.rst example-rl-pong.rst example-policy-gradient.rst example-parameter-server.rst diff --git a/doc/source/pbt.rst b/doc/source/pbt.rst new file mode 100644 index 000000000..217495645 --- /dev/null +++ b/doc/source/pbt.rst @@ -0,0 +1,33 @@ +Population Based Training +========================= + +Ray Tune includes a distributed implementation of `Population Based Training (PBT) `__. + + +PBT Scheduler +------------- + +Ray Tune's PBT scheduler can be plugged in on top of an existing grid or random search experiment. This can be enabled by setting the ``scheduler`` parameter of ``run_experiments``, e.g. + +.. code-block:: python + + run_experiments( + {...}, + scheduler=PopulationBasedTraining( + time_attr='time_total_s', + reward_attr='mean_accuracy', + perturbation_interval=600.0, + hyperparameter_mutations={ + "lr": [1e-3, 5e-4, 1e-4, 5e-5, 1e-5], + "alpha": lambda: random.uniform(0.0, 1.0), + ... + })) + +When the PBT scheduler is enabled, each trial variant is treated as a member of the population. Periodically, top-performing trials are checkpointed (this requires your Trainable to support `checkpointing `__). Low-performing trials clone the checkpoints of top performers and perturb the configurations in the hope of discovering an even better variation. + +You can run this `toy PBT example `__ to get an idea of how how PBT operates. When training in PBT mode, a single trial may see many different hyperparameters over its lifetime, which is recorded in its ``result.json`` file. The following figure generated by the example shows PBT discovering new hyperparams over the course of a single experiment: + +.. image:: pbt.png + +.. autoclass:: ray.tune.pbt.PopulationBasedTraining + diff --git a/doc/source/tune-api.svg b/doc/source/tune-api.svg new file mode 100644 index 000000000..9b0c0a3e6 --- /dev/null +++ b/doc/source/tune-api.svg @@ -0,0 +1,4 @@ + + + + diff --git a/doc/source/tune.rst b/doc/source/tune.rst index 0d50bd5d6..537c0aaf6 100644 --- a/doc/source/tune.rst +++ b/doc/source/tune.rst @@ -5,7 +5,7 @@ This document describes Ray Tune, a hyperparameter tuning framework for long-run It has the following features: -- Scalable implementations of search algorithms such as `Population Based Training (PBT) <#population-based-training>`__, `Median Stopping Rule `__, and `HyperBand `__. +- Scalable implementations of search algorithms such as `Population Based Training (PBT) `__, `Median Stopping Rule `__, and `HyperBand `__. - Integration with visualization tools such as `TensorBoard `__, `rllab's VisKit `__, and a `parallel coordinates visualization `__. @@ -19,6 +19,8 @@ You can find the code for Ray Tune `here on GitHub `__. Incremental results will be synced to local disk on the head node of the cluster and optionally uploaded to the specified ``upload_dir`` (e.g. S3 path). +Trial Schedulers +---------------- + +By default, Ray Tune schedules trials in serial order with the ``FIFOScheduler`` class. However, you can also specify a custom scheduling algorithm that can early stop trials, perturb parameters, or incorporate suggestions from an external service. Currently implemented trial schedulers include `Population Based Training (PBT) `__, `Median Stopping Rule `__, and `HyperBand `__. + Visualizing Results ------------------- @@ -135,72 +142,10 @@ By default, each random variable and grid search point is sampled once. To take For more information on variant generation, see `variant_generator.py `__. -Early Stopping --------------- - -To reduce costs, long-running trials can often be early stopped if their initial performance is not promising. Ray Tune allows early stopping algorithms to be plugged in on top of existing grid or random searches. This can be enabled by setting the ``scheduler`` parameter of ``run_experiments``, e.g. - -.. code-block:: python - - run_experiments({...}, scheduler=HyperBandScheduler()) - -An example of this can be found in `hyperband_example.py `__. The progress of one such HyperBand run is shown below. - -:: - - == Status == - Using HyperBand: num_stopped=0 total_brackets=5 - Round #0: - Bracket(n=5, r=100, completed=80%): {'PAUSED': 4, 'PENDING': 1} - Bracket(n=8, r=33, completed=23%): {'PAUSED': 4, 'PENDING': 4} - Bracket(n=15, r=11, completed=4%): {'RUNNING': 2, 'PAUSED': 2, 'PENDING': 11} - Bracket(n=34, r=3, completed=0%): {'RUNNING': 2, 'PENDING': 32} - Bracket(n=81, r=1, completed=0%): {'PENDING': 38} - Resources used: 4/4 CPUs, 0/0 GPUs - Result logdir: ~/ray_results/hyperband_test - PAUSED trials: - - my_class_0_height=99,width=43: PAUSED [pid=11664], 0 s, 100 ts, 97.1 rew - - my_class_11_height=85,width=81: PAUSED [pid=11771], 0 s, 33 ts, 32.8 rew - - my_class_12_height=0,width=52: PAUSED [pid=11785], 0 s, 33 ts, 0 rew - - my_class_19_height=44,width=88: PAUSED [pid=11811], 0 s, 11 ts, 5.47 rew - - my_class_27_height=96,width=84: PAUSED [pid=11840], 0 s, 11 ts, 12.5 rew - ... 5 more not shown - PENDING trials: - - my_class_10_height=12,width=25: PENDING - - my_class_13_height=90,width=45: PENDING - - my_class_14_height=69,width=45: PENDING - - my_class_15_height=41,width=11: PENDING - - my_class_16_height=57,width=69: PENDING - ... 81 more not shown - RUNNING trials: - - my_class_23_height=75,width=51: RUNNING [pid=11843], 0 s, 1 ts, 1.47 rew - - my_class_26_height=16,width=48: RUNNING - - my_class_31_height=40,width=10: RUNNING - - my_class_53_height=28,width=96: RUNNING - -Ray Tune also implements an `asynchronous version of HyperBand `__, providing better parallelism and avoids straggler issues during eliminations. An example of this can be found in `async_hyperband_example.py `__. We recommend using this over the vanilla HyperBand scheduler. - -.. note:: Some trial schedulers such as HyperBand and PBT require your Trainable to support checkpointing, which is described in the next section. Checkpointing enables the scheduler to multiplex many concurrent trials onto a limited size cluster. - -Currently we support the following early stopping algorithms, or you can write your own that implements the `TrialScheduler `__ interface. - -.. autoclass:: ray.tune.median_stopping_rule.MedianStoppingRule -.. autoclass:: ray.tune.hyperband.HyperBandScheduler -.. autoclass:: ray.tune.async_hyperband.AsyncHyperBandScheduler - -Population Based Training -------------------------- - -Ray Tune includes a distributed implementation of `Population Based Training (PBT) `__. PBT also requires your Trainable to support checkpointing. You can run this `toy PBT example `__ to get an idea of how how PBT operates. When training in PBT mode, the set of trial variations is treated as the population, so a single trial may see many different hyperparameters over its lifetime, which is recorded in the ``result.json`` file. The following figure generated by the example shows PBT discovering new hyperparams over the course of a single experiment: - -.. image:: pbt.png - -.. autoclass:: ray.tune.pbt.PopulationBasedTraining - Trial Checkpointing ------------------- -To enable checkpoint / resume, you must subclass ``Trainable`` and implement its ``_train``, ``_save``, and ``_restore`` abstract methods `(example) `__: Implementing this interface is required to support resource multiplexing in schedulers such as HyperBand and PBT. +To enable checkpointing, you must implement a Trainable class (Trainable functions are not checkpointable, since they never return control back to their caller). The easiest way to do this is to subclass the pre-defined ``Trainable`` class and implement its ``_train``, ``_save``, and ``_restore`` abstract methods `(example) `__: Implementing this interface is required to support resource multiplexing in schedulers such as HyperBand and PBT. For TensorFlow model training, this would look something like this `(full tensorflow example) `__: