wehub/ray-project--ray
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:17:40 +08:00
commit f1825c8ceb
10096 changed files with 2364182 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/tune/api/api.rst
+30
View File
@@ -0,0 +1,30 @@
.. _tune-api-ref:
Ray Tune API
============
.. tip:: We'd love to hear your feedback on using Tune - `get in touch <https://forms.gle/PTRvGLbKRdUfuzQo9>`_!
This section contains a reference for the Tune API. If there is anything missing, please open an issue
on `GitHub`_.
.. _`GitHub`: https://github.com/ray-project/ray/issues
.. toctree::
:maxdepth: 2
execution.rst
result_grid.rst
trainable.rst
search_space.rst
suggestion.rst
schedulers.rst
stoppers.rst
reporters.rst
syncing.rst
logging.rst
callbacks.rst
env.rst
integration.rst
internals.rst
cli.rst
doc/source/tune/api/callbacks.rst
+63
View File
@@ -0,0 +1,63 @@
.. _tune-callbacks-docs:
Tune Callbacks (tune.Callback)
==============================
See :doc:`this user guide </tune/tutorials/tune-metrics>` for more details.
.. seealso::
:doc:`Tune's built-in loggers </tune/api/logging>` use the ``Callback`` interface.
Callback Interface
------------------
Callback Initialization and Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. currentmodule:: ray.tune
.. autosummary::
:nosignatures:
:toctree: doc/
Callback
.. autosummary::
:nosignatures:
:toctree: doc/
Callback.setup
Callback Hooks
~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
Callback.on_checkpoint
Callback.on_experiment_end
Callback.on_step_begin
Callback.on_step_end
Callback.on_trial_complete
Callback.on_trial_error
Callback.on_trial_restore
Callback.on_trial_result
Callback.on_trial_save
Callback.on_trial_start
Stateful Callbacks
~~~~~~~~~~~~~~~~~~
The following methods must be overridden for stateful callbacks to be saved/restored
properly by Tune.
.. autosummary::
:nosignatures:
:toctree: doc/
Callback.get_state
Callback.set_state
doc/source/tune/api/cli.rst
+39
View File
@@ -0,0 +1,39 @@
Tune CLI (Experimental)
=======================
``tune`` has an easy-to-use command line interface (CLI) to manage and monitor your experiments on Ray.
Here is an example command line call:
``tune list-trials``: List tabular information about trials within an experiment.
Empty columns will be dropped by default. Add the ``--sort`` flag to sort the output by specific columns.
Add the ``--filter`` flag to filter the output in the format ``"<column> <operator> <value>"``.
Add the ``--output`` flag to write the trial information to a specific file (CSV or Pickle).
Add the ``--columns`` and ``--result-columns`` flags to select specific columns to display.
.. code-block:: bash
$ tune list-trials [EXPERIMENT_DIR] --output note.csv
+------------------+-----------------------+------------+
| trainable_name | experiment_tag | trial_id |
|------------------+-----------------------+------------|
| MyTrainableClass | 0_height=40,width=37 | 87b54a1d |
| MyTrainableClass | 1_height=21,width=70 | 23b89036 |
| MyTrainableClass | 2_height=99,width=90 | 518dbe95 |
| MyTrainableClass | 3_height=54,width=21 | 7b99a28a |
| MyTrainableClass | 4_height=90,width=69 | ae4e02fb |
+------------------+-----------------------+------------+
Dropped columns: ['status', 'last_update_time']
Please increase your terminal size to view remaining columns.
Output saved at: note.csv
$ tune list-trials [EXPERIMENT_DIR] --filter "trial_id == 7b99a28a"
+------------------+-----------------------+------------+
| trainable_name | experiment_tag | trial_id |
|------------------+-----------------------+------------|
| MyTrainableClass | 3_height=54,width=21 | 7b99a28a |
+------------------+-----------------------+------------+
Dropped columns: ['status', 'last_update_time']
Please increase your terminal size to view remaining columns.
doc/source/tune/api/env.rst
+96
View File
@@ -0,0 +1,96 @@
.. _tune-env-vars:
Environment variables used by Ray Tune
--------------------------------------
Some of Ray Tune's behavior can be configured using environment variables.
These are the environment variables Ray Tune currently considers:
* **TUNE_DISABLE_AUTO_CALLBACK_LOGGERS**: Ray Tune automatically adds a CSV and
JSON logger callback if they haven't been passed. Setting this variable to
`1` disables this automatic creation. Please note that this will most likely
affect analyzing your results after the tuning run.
* **TUNE_DISABLE_AUTO_INIT**: Disable automatically calling ``ray.init()`` if
not attached to a Ray session.
* **TUNE_DISABLE_DATED_SUBDIR**: Ray Tune automatically adds a date string to experiment
directories when the name is not specified explicitly or the trainable isn't passed
as a string. Setting this environment variable to ``1`` disables adding these date strings.
* **TUNE_DISABLE_STRICT_METRIC_CHECKING**: When you report metrics to Tune via
``tune.report()`` and passed a ``metric`` parameter to ``Tuner()``, a scheduler,
or a search algorithm, Tune will error
if the metric was not reported in the result. Setting this environment variable
to ``1`` will disable this check.
* **TUNE_DISABLE_SIGINT_HANDLER**: Ray Tune catches SIGINT signals (e.g. sent by
Ctrl+C) to gracefully shutdown and do a final checkpoint. Setting this variable
to ``1`` will disable signal handling and stop execution right away. Defaults to
``0``.
* **TUNE_FORCE_TRIAL_CLEANUP_S**: By default, Ray Tune will gracefully terminate trials,
letting them finish the current training step and any user-defined cleanup.
Setting this variable to a non-zero, positive integer will cause trials to be forcefully
terminated after a grace period of that many seconds. Defaults to ``600`` (seconds).
* **TUNE_FUNCTION_THREAD_TIMEOUT_S**: Time in seconds the function API waits
for threads to finish after instructing them to complete. Defaults to ``2``.
* **TUNE_GLOBAL_CHECKPOINT_S**: Time in seconds that limits how often
experiment state is checkpointed. If not, set this will default to ``'auto'``.
``'auto'`` measures the time it takes to snapshot the experiment state
and adjusts the period so that ~5% of the driver's time is spent on snapshotting.
You should set this to a fixed value (ex: ``TUNE_GLOBAL_CHECKPOINT_S=60``)
to snapshot your experiment state every X seconds.
* **TUNE_MAX_LEN_IDENTIFIER**: Maximum length of trial subdirectory names (those
with the parameter values in them)
* **TUNE_MAX_PENDING_TRIALS_PG**: Maximum number of pending trials when placement groups are used. Defaults
to ``auto``, which will be updated to ``max(200, cluster_cpus * 1.1)`` for random/grid search and ``1``
for any other search algorithms.
* **TUNE_PLACEMENT_GROUP_PREFIX**: Prefix for placement groups created by Ray Tune. This prefix is used
e.g. to identify placement groups that should be cleaned up on start/stop of the tuning run. This is
initialized to a unique name at the start of the first run.
* **TUNE_PLACEMENT_GROUP_RECON_INTERVAL**: How often to reconcile placement groups. Reconcilation is
used to make sure that the number of requested placement groups and pending/running trials are in sync.
In normal circumstances these shouldn't differ anyway, but reconcilation makes sure to capture cases when
placement groups are manually destroyed. Reconcilation doesn't take much time, but it can add up when
running a large number of short trials. Defaults to every ``5`` (seconds).
* **TUNE_PRINT_ALL_TRIAL_ERRORS**: If ``1``, will print all trial errors as they come up. Otherwise, errors
will only be saved as text files to the trial directory and not printed. Defaults to ``1``.
* **TUNE_RESULT_BUFFER_LENGTH**: Ray Tune can buffer results from trainables before they are passed
to the driver. Enabling this might delay scheduling decisions, as trainables are speculatively
continued. Setting this to ``1`` disables result buffering. Cannot be used with ``checkpoint_at_end``.
Defaults to disabled.
* **TUNE_RESULT_DELIM**: Delimiter used for nested entries in
:class:`ExperimentAnalysis <ray.tune.ExperimentAnalysis>` dataframes. Defaults to ``.`` (but will be
changed to ``/`` in future versions of Ray).
* **TUNE_RESULT_BUFFER_MAX_TIME_S**: Similarly, Ray Tune buffers results up to ``number_of_trial/10`` seconds,
but never longer than this value. Defaults to 100 (seconds).
* **TUNE_RESULT_BUFFER_MIN_TIME_S**: Additionally, you can specify a minimum time to buffer results. Defaults to 0.
* **TUNE_WARN_THRESHOLD_S**: Threshold for logging if an Tune event loop operation takes too long. Defaults to 0.5 (seconds).
* **TUNE_WARN_INSUFFICIENT_RESOURCE_THRESHOLD_S**: Threshold for throwing a warning if no active trials are in ``RUNNING`` state
for this amount of seconds. If the Ray Tune job is stuck in this state (most likely due to insufficient resources),
the warning message is printed repeatedly every this amount of seconds. Defaults to 60 (seconds).
* **TUNE_WARN_INSUFFICIENT_RESOURCE_THRESHOLD_S_AUTOSCALER**: Threshold for throwing a warning when the autoscaler is enabled and
if no active trials are in ``RUNNING`` state for this amount of seconds.
If the Ray Tune job is stuck in this state (most likely due to insufficient resources), the warning message is printed
repeatedly every this amount of seconds. Defaults to 60 (seconds).
* **TUNE_WARN_SLOW_EXPERIMENT_CHECKPOINT_SYNC_THRESHOLD_S**: Threshold for logging a warning if the experiment state syncing
takes longer than this time in seconds. The experiment state files should be very lightweight, so this should not take longer than ~5 seconds.
Defaults to 5 (seconds).
* **TUNE_STATE_REFRESH_PERIOD**: Frequency of updating the resource tracking from Ray. Defaults to 10 (seconds).
* **TUNE_RESTORE_RETRY_NUM**: The number of retries that are done before a particular trial's restore is determined
unsuccessful. After that, the trial is not restored to its previous checkpoint but rather from scratch.
Default is ``0``. While this retry counter is taking effect, per trial failure number will not be incremented, which
is compared against ``max_failures``.
* **TUNE_ONLY_STORE_CHECKPOINT_SCORE_ATTRIBUTE**: If set to ``1``, only the metric defined by ``checkpoint_score_attribute``
will be stored with each ``Checkpoint``. As a result, ``Result.best_checkpoints`` will contain only this metric,
omitting others that would normally be included. This can significantly reduce memory usage, especially when many
checkpoints are stored or when metrics are large. Defaults to ``0`` (i.e., all metrics are stored).
* **RAY_AIR_FULL_TRACEBACKS**: If set to 1, will print full tracebacks for training functions,
including internal code paths. Otherwise, abbreviated tracebacks that only show user code
are printed. Defaults to 0 (disabled).
* **RAY_AIR_NEW_OUTPUT**: If set to 0, this disables
the `experimental new console output <https://github.com/ray-project/ray/issues/36949>`_.
There are some environment variables that are mostly relevant for integrated libraries:
* **WANDB_API_KEY**: Weights and Biases API key. You can also use ``wandb login``
instead.
doc/source/tune/api/execution.rst
+58
View File
@@ -0,0 +1,58 @@
Tune Execution (tune.Tuner)
===========================
.. _tune-run-ref:
Tuner
-----
.. currentmodule:: ray.tune
.. autosummary::
:nosignatures:
:toctree: doc/
Tuner
.. autosummary::
:nosignatures:
:toctree: doc/
Tuner.fit
Tuner.get_results
Tuner Configuration
~~~~~~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
TuneConfig
RunConfig
CheckpointConfig
FailureConfig
Restoring a Tuner
~~~~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
Tuner.restore
Tuner.can_restore
tune.run_experiments
--------------------
.. autosummary::
:nosignatures:
:toctree: doc/
run_experiments
run
Experiment
TuneError
doc/source/tune/api/integration.rst
+42
View File
@@ -0,0 +1,42 @@
.. _tune-integration:
External library integrations for Ray Tune
===========================================
.. currentmodule:: ray
.. _tune-integration-pytorch-lightning:
PyTorch Lightning (tune.integration.pytorch_lightning)
------------------------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.integration.pytorch_lightning.TuneReportCheckpointCallback
.. _tune-integration-xgboost:
XGBoost (tune.integration.xgboost)
----------------------------------
.. autosummary::
:nosignatures:
:template: autosummary/class_without_autosummary.rst
:toctree: doc/
~tune.integration.xgboost.TuneReportCheckpointCallback
.. _tune-integration-lightgbm:
LightGBM (tune.integration.lightgbm)
------------------------------------
.. autosummary::
:nosignatures:
:template: autosummary/class_without_autosummary.rst
:toctree: doc/
~tune.integration.lightgbm.TuneReportCheckpointCallback
doc/source/tune/api/internals.rst
+43
View File
@@ -0,0 +1,43 @@
Tune Internals
==============
.. _raytrialexecutor-docstring:
TunerInternal
---------------
.. autoclass:: ray.tune.impl.tuner_internal.TunerInternal
:members:
.. _trial-docstring:
Trial
-----
.. autoclass:: ray.tune.experiment.trial.Trial
:members:
FunctionTrainable
-----------------
.. autoclass:: ray.tune.trainable.function_trainable.FunctionTrainable
.. autofunction:: ray.tune.trainable.function_trainable.wrap_function
Registry
--------
.. autofunction:: ray.tune.register_trainable
.. autofunction:: ray.tune.register_env
Output
------
.. autoclass:: ray.tune.experimental.output.ProgressReporter
.. autoclass:: ray.tune.experimental.output.TrainReporter
.. autoclass:: ray.tune.experimental.output.TuneReporterBase
.. autoclass:: ray.tune.experimental.output.TuneTerminalReporter
doc/source/tune/api/logging.rst
+126
View File
@@ -0,0 +1,126 @@
.. _loggers-docstring:
Tune Loggers (tune.logger)
==========================
Tune automatically uses loggers for TensorBoard, CSV, and JSON formats.
By default, Tune only logs the returned result dictionaries from the training function.
If you need to log something lower level like model weights or gradients,
see :ref:`Trainable Logging <trainable-logging>`.
.. note::
Tune's per-trial ``Logger`` classes have been deprecated. Use the ``LoggerCallback`` interface instead.
.. currentmodule:: ray
.. _logger-interface:
LoggerCallback Interface (tune.logger.LoggerCallback)
-----------------------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.logger.LoggerCallback
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.logger.LoggerCallback.log_trial_start
~tune.logger.LoggerCallback.log_trial_restore
~tune.logger.LoggerCallback.log_trial_save
~tune.logger.LoggerCallback.log_trial_result
~tune.logger.LoggerCallback.log_trial_end
Tune Built-in Loggers
---------------------
.. autosummary::
:nosignatures:
:toctree: doc/
tune.logger.JsonLoggerCallback
tune.logger.CSVLoggerCallback
tune.logger.TBXLoggerCallback
MLFlow Integration
------------------
Tune also provides a logger for `MLflow <https://mlflow.org>`_.
You can install MLflow via ``pip install mlflow``.
See the :doc:`tutorial here </tune/examples/tune-mlflow>`.
.. autosummary::
:nosignatures:
:toctree: doc/
~air.integrations.mlflow.MLflowLoggerCallback
~air.integrations.mlflow.setup_mlflow
Wandb Integration
-----------------
Tune also provides a logger for `Weights & Biases <https://www.wandb.ai/>`_.
You can install Wandb via ``pip install wandb``.
See the :doc:`tutorial here </tune/examples/tune-wandb>`.
.. autosummary::
:nosignatures:
:toctree: doc/
~air.integrations.wandb.WandbLoggerCallback
~air.integrations.wandb.setup_wandb
Comet Integration
------------------------------
Tune also provides a logger for `Comet <https://www.comet.com/>`_.
You can install Comet via ``pip install comet-ml``.
See the :doc:`tutorial here </tune/examples/tune-comet>`.
.. autosummary::
:nosignatures:
:toctree: doc/
~air.integrations.comet.CometLoggerCallback
Aim Integration
---------------
Tune also provides a logger for the `Aim <https://aimstack.io/>`_ experiment tracker.
You can install Aim via ``pip install aim``.
See the :doc:`tutorial here </tune/examples/tune-aim>`.
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.logger.aim.AimLoggerCallback
Other Integrations
------------------
Viskit
~~~~~~
Tune automatically integrates with `Viskit <https://github.com/vitchyr/viskit>`_ via the ``CSVLoggerCallback`` outputs.
To use VisKit (you may have to install some dependencies), run:
.. code-block:: bash
$ git clone https://github.com/vitchyr/viskit.git
$ python viskit/viskit/frontend.py ~/ray_results/my_experiment
The non-relevant metrics (like timing stats) can be disabled on the left to show only the
relevant ones (like accuracy, loss, etc.).
.. image:: ../images/ray-tune-viskit.png
doc/source/tune/api/reporters.rst
+119
View File
@@ -0,0 +1,119 @@
.. _tune-reporter-doc:
Tune Console Output (Reporters)
===============================
By default, Tune reports experiment progress periodically to the command-line as follows.
.. code-block:: bash
== Status ==
Memory usage on this node: 11.4/16.0 GiB
Using FIFO scheduling algorithm.
Resources requested: 4/12 CPUs, 0/0 GPUs, 0.0/3.17 GiB heap, 0.0/1.07 GiB objects
Result logdir: /Users/foo/ray_results/myexp
Number of trials: 4 (4 RUNNING)
+----------------------+----------+---------------------+-----------+--------+--------+--------+--------+------------------+-------+
| Trial name | status | loc | param1 | param2 | param3 | acc | loss | total time (s) | iter |
|----------------------+----------+---------------------+-----------+--------+--------+--------+--------+------------------+-------|
| MyTrainable_a826033a | RUNNING | 10.234.98.164:31115 | 0.303706 | 0.0761 | 0.4328 | 0.1289 | 1.8572 | 7.54952 | 15 |
| MyTrainable_a8263fc6 | RUNNING | 10.234.98.164:31117 | 0.929276 | 0.158 | 0.3417 | 0.4865 | 1.6307 | 7.0501 | 14 |
| MyTrainable_a8267914 | RUNNING | 10.234.98.164:31111 | 0.068426 | 0.0319 | 0.1147 | 0.9585 | 1.9603 | 7.0477 | 14 |
| MyTrainable_a826b7bc | RUNNING | 10.234.98.164:31112 | 0.729127 | 0.0748 | 0.1784 | 0.1797 | 1.7161 | 7.05715 | 14 |
+----------------------+----------+---------------------+-----------+--------+--------+--------+--------+------------------+-------+
Note that columns will be hidden if they are completely empty. The output can be configured in various ways by
instantiating a ``CLIReporter`` instance (or ``JupyterNotebookReporter`` if you're using jupyter notebook).
Here's an example:
.. TODO: test these snippets
.. code-block:: python
import ray.tune
from ray.tune import CLIReporter
# Limit the number of rows.
reporter = CLIReporter(max_progress_rows=10)
# Add a custom metric column, in addition to the default metrics.
# Note that this must be a metric that is returned in your training results.
reporter.add_metric_column("custom_metric")
tuner = tune.Tuner(my_trainable, run_config=ray.tune.RunConfig(progress_reporter=reporter))
results = tuner.fit()
Extending ``CLIReporter`` lets you control reporting frequency. For example:
.. code-block:: python
from ray.tune.experiment.trial import Trial
class ExperimentTerminationReporter(CLIReporter):
def should_report(self, trials, done=False):
"""Reports only on experiment termination."""
return done
tuner = tune.Tuner(my_trainable, run_config=ray.tune.RunConfig(progress_reporter=ExperimentTerminationReporter()))
results = tuner.fit()
class TrialTerminationReporter(CLIReporter):
def __init__(self):
super(TrialTerminationReporter, self).__init__()
self.num_terminated = 0
def should_report(self, trials, done=False):
"""Reports only on trial termination events."""
old_num_terminated = self.num_terminated
self.num_terminated = len([t for t in trials if t.status == Trial.TERMINATED])
return self.num_terminated > old_num_terminated
tuner = tune.Tuner(my_trainable, run_config=ray.tune.RunConfig(progress_reporter=TrialTerminationReporter()))
results = tuner.fit()
The default reporting style can also be overridden more broadly by extending the ``ProgressReporter`` interface directly. Note that you can print to any output stream, file etc.
.. code-block:: python
from ray.tune import ProgressReporter
class CustomReporter(ProgressReporter):
def should_report(self, trials, done=False):
return True
def report(self, trials, *sys_info):
print(*sys_info)
print("\n".join([str(trial) for trial in trials]))
tuner = tune.Tuner(my_trainable, run_config=ray.tune.RunConfig(progress_reporter=CustomReporter()))
results = tuner.fit()
.. currentmodule:: ray.tune
Reporter Interface (tune.ProgressReporter)
------------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
ProgressReporter
.. autosummary::
:nosignatures:
:toctree: doc/
ProgressReporter.report
ProgressReporter.should_report
Tune Built-in Reporters
-----------------------
.. autosummary::
:nosignatures:
:toctree: doc/
CLIReporter
JupyterNotebookReporter
doc/source/tune/api/result_grid.rst
+55
View File
@@ -0,0 +1,55 @@
.. _air-results-ref:
.. _tune-analysis-docs:
.. _result-grid-docstring:
Tune Experiment Results (tune.ResultGrid)
=========================================
ResultGrid (tune.ResultGrid)
----------------------------
.. currentmodule:: ray
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.ResultGrid
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.ResultGrid.get_best_result
~tune.ResultGrid.get_dataframe
.. _result-docstring:
Result (tune.Result)
---------------------
.. autosummary::
:nosignatures:
:template: autosummary/class_without_autosummary.rst
:toctree: doc/
~tune.Result
.. _exp-analysis-docstring:
ExperimentAnalysis (tune.ExperimentAnalysis)
--------------------------------------------
.. note::
An `ExperimentAnalysis` is the output of the ``tune.run`` API.
It's now recommended to use :meth:`Tuner.fit <ray.tune.Tuner.fit>`,
which outputs a `ResultGrid` object.
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.ExperimentAnalysis
doc/source/tune/api/schedulers.rst
+371
View File
@@ -0,0 +1,371 @@
.. _tune-schedulers:
Tune Trial Schedulers (tune.schedulers)
=======================================
In Tune, some hyperparameter optimization algorithms are written as "scheduling algorithms".
These Trial Schedulers can early terminate bad trials, pause trials, clone trials,
and alter hyperparameters of a running trial.
All Trial Schedulers take in a ``metric``, which is a value returned in the result dict of your
Trainable and is maximized or minimized according to ``mode``.
.. code-block:: python
from ray import tune
from ray.tune.schedulers import ASHAScheduler
def train_fn(config):
# This objective function is just for demonstration purposes
tune.report({"loss": config["param"]})
tuner = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(
scheduler=ASHAScheduler(),
metric="loss",
mode="min",
num_samples=10,
),
param_space={"param": tune.uniform(0, 1)},
)
results = tuner.fit()
.. currentmodule:: ray.tune.schedulers
.. _tune-scheduler-hyperband:
ASHA (tune.schedulers.ASHAScheduler)
------------------------------------
The `ASHA <https://openreview.net/forum?id=S1Y7OOlRZ>`__ scheduler can be used by
setting the ``scheduler`` parameter of ``tune.TuneConfig``, which is taken in by ``Tuner``, e.g.
.. code-block:: python
from ray import tune
from ray.tune.schedulers import ASHAScheduler
asha_scheduler = ASHAScheduler(
time_attr='training_iteration',
metric='loss',
mode='min',
max_t=100,
grace_period=10,
reduction_factor=3,
brackets=1,
)
tuner = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(scheduler=asha_scheduler),
)
results = tuner.fit()
Compared to the original version of HyperBand, this implementation provides better
parallelism and avoids straggler issues during eliminations.
**We recommend using this over the standard HyperBand scheduler.**
An example of this can be found here: :doc:`/tune/examples/includes/async_hyperband_example`.
Even though the original paper mentions a bracket count of 3, discussions with the authors concluded
that the value should be left to 1 bracket.
This is the default used if no value is provided for the ``brackets`` argument.
.. autosummary::
:nosignatures:
:toctree: doc/
:template: autosummary/class_without_autosummary.rst
AsyncHyperBandScheduler
ASHAScheduler
.. _tune-original-hyperband:
HyperBand (tune.schedulers.HyperBandScheduler)
----------------------------------------------
Tune implements the `standard version of HyperBand <https://arxiv.org/abs/1603.06560>`__.
**We recommend using the ASHA Scheduler over the standard HyperBand scheduler.**
.. autosummary::
:nosignatures:
:toctree: doc/
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 <https://blog.ml.cmu.edu/2018/12/12/massively-parallel-hyperparameter-optimization/>`_ 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 <https://blog.ml.cmu.edu/2018/12/12/massively-parallel-hyperparameter-optimization/>`_ 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.
.. _tune-scheduler-msr:
Median Stopping Rule (tune.schedulers.MedianStoppingRule)
---------------------------------------------------------
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.
.. autosummary::
:nosignatures:
:toctree: doc/
MedianStoppingRule
.. _tune-scheduler-pbt:
Population Based Training (tune.schedulers.PopulationBasedTraining)
-------------------------------------------------------------------
Tune includes a distributed implementation of `Population Based Training (PBT) <https://www.deepmind.com/blog/population-based-training-of-neural-networks>`__.
This can be enabled by setting the ``scheduler`` parameter of ``tune.TuneConfig``, which is taken in by ``Tuner``, e.g.
.. code-block:: python
from ray import tune
from ray.tune.schedulers import PopulationBasedTraining
pbt_scheduler = PopulationBasedTraining(
time_attr='training_iteration',
metric='loss',
mode='min',
perturbation_interval=1,
hyperparam_mutations={
"lr": [1e-3, 5e-4, 1e-4, 5e-5, 1e-5],
"alpha": tune.uniform(0.0, 1.0),
}
)
tuner = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(
num_samples=4,
scheduler=pbt_scheduler,
),
)
tuner.fit()
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 :ref:`save and restore <tune-trial-checkpoint>`).
**Low-performing trials clone the hyperparameter configurations of top performers and
perturb them** slightly in the hopes of discovering even better hyperparameter settings.
**Low-performing trials also resume from the checkpoints of the top performers**, allowing
the trials to explore the new hyperparameter configuration starting from a partially
trained model (e.g. by copying model weights from one of the top-performing trials).
Take a look at :doc:`/tune/examples/pbt_visualization/pbt_visualization` to get an idea
of how PBT operates. :doc:`/tune/examples/pbt_guide` gives more examples
of PBT usage.
.. autosummary::
:nosignatures:
:toctree: doc/
PopulationBasedTraining
.. _tune-scheduler-pbt-replay:
Population Based Training Replay (tune.schedulers.PopulationBasedTrainingReplay)
--------------------------------------------------------------------------------
Tune includes a utility to replay hyperparameter schedules of Population Based Training runs.
You just specify an existing experiment directory and the ID of the trial you would
like to replay. The scheduler accepts only one trial, and it will update its
config according to the obtained schedule.
.. code-block:: python
from ray import tune
from ray.tune.schedulers import PopulationBasedTrainingReplay
replay = PopulationBasedTrainingReplay(
experiment_dir="~/ray_results/pbt_experiment/",
trial_id="XXXXX_00001"
)
tuner = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(scheduler=replay)
)
results = tuner.fit()
See :ref:`here for an example <tune-advanced-tutorial-pbt-replay>` on how to use the
replay utility in practice.
.. autosummary::
:nosignatures:
:toctree: doc/
PopulationBasedTrainingReplay
.. _tune-scheduler-pb2:
Population Based Bandits (PB2) (tune.schedulers.pb2.PB2)
--------------------------------------------------------
Tune includes a distributed implementation of `Population Based Bandits (PB2) <https://arxiv.org/abs/2002.02518>`__.
This algorithm builds upon PBT, with the main difference being that instead of using random perturbations,
PB2 selects new hyperparameter configurations using a Gaussian Process model.
The Tune implementation of PB2 requires scikit-learn to be installed:
.. code-block:: bash
pip install scikit-learn
PB2 can be enabled by setting the ``scheduler`` parameter of ``tune.TuneConfig`` which is taken in by ``Tuner``, e.g.:
.. code-block:: python
from ray.tune.schedulers.pb2 import PB2
pb2_scheduler = PB2(
time_attr='time_total_s',
metric='mean_accuracy',
mode='max',
perturbation_interval=600.0,
hyperparam_bounds={
"lr": [1e-3, 1e-5],
"alpha": [0.0, 1.0],
...
}
)
tuner = tune.Tuner( ... , tune_config=tune.TuneConfig(scheduler=pb2_scheduler))
results = tuner.fit()
When the PB2 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 :ref:`save and restore <tune-trial-checkpoint>`).
Low-performing trials clone the checkpoints of top performers and perturb the configurations
in the hope of discovering an even better variation.
The primary motivation for PB2 is the ability to find promising hyperparameters with only a small population size.
With that in mind, you can run this :doc:`PB2 PPO example </tune/examples/includes/pb2_ppo_example>` to compare PB2 vs. PBT,
with a population size of ``4`` (as in the paper).
The example uses the ``BipedalWalker`` environment so does not require any additional licenses.
.. autosummary::
:nosignatures:
:toctree: doc/
pb2.PB2
.. _tune-scheduler-bohb:
BOHB (tune.schedulers.HyperBandForBOHB)
---------------------------------------
This class is a variant of HyperBand that enables the `BOHB Algorithm <https://arxiv.org/abs/1807.01774>`_.
This implementation is true to the original HyperBand implementation and does not implement pipelining nor
straggler mitigation.
This is to be used in conjunction with the Tune BOHB search algorithm.
See :ref:`TuneBOHB <suggest-TuneBOHB>` for package requirements, examples, and details.
An example of this in use can be found here: :doc:`/tune/examples/includes/bohb_example`.
.. autosummary::
:nosignatures:
:toctree: doc/
HyperBandForBOHB
.. _tune-resource-changing-scheduler:
ResourceChangingScheduler
-------------------------
This class is a utility scheduler, allowing for trial resource requirements to be changed during tuning.
It wraps around another scheduler and uses its decisions.
* If you are using the Trainable (class) API for tuning, your Trainable must implement ``Trainable.update_resources``,
which will let your model know about the new resources assigned. You can also obtain the current trial resources
by calling ``Trainable.trial_resources``.
* If you are using the functional API for tuning, get the current trial resources obtained by calling
`tune.get_trial_resources()` inside the training function.
The function should be able to :ref:`load and save checkpoints <tune-function-trainable-checkpointing>`
(the latter preferably every iteration).
An example of this in use can be found here: :doc:`/tune/examples/includes/xgboost_dynamic_resources_example`.
.. autosummary::
:nosignatures:
:toctree: doc/
ResourceChangingScheduler
resource_changing_scheduler.DistributeResources
resource_changing_scheduler.DistributeResourcesToTopJob
FIFOScheduler (Default Scheduler)
---------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
FIFOScheduler
TrialScheduler Interface
------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
TrialScheduler
.. autosummary::
:nosignatures:
:toctree: doc/
TrialScheduler.choose_trial_to_run
TrialScheduler.on_trial_result
TrialScheduler.on_trial_complete
Shim Instantiation (tune.create_scheduler)
------------------------------------------
There is also a shim function that constructs the scheduler based on the provided string.
This can be useful if the scheduler you want to use changes often (e.g., specifying the scheduler
via a CLI option or config file).
.. autosummary::
:nosignatures:
:toctree: doc/
create_scheduler
doc/source/tune/api/search_space.rst
+116
View File
@@ -0,0 +1,116 @@
.. _tune-search-space:
Tune Search Space API
=====================
This section covers the functions you can use to define your search spaces.
.. caution::
Not all Search Algorithms support all distributions. In particular,
``tune.sample_from`` and ``tune.grid_search`` are often unsupported.
The default :ref:`tune-basicvariant` supports all distributions.
.. tip::
Avoid passing large objects as values in the search space, as that will incur a performance overhead.
Use :func:`tune.with_parameters <ray.tune.with_parameters>` to pass large objects in or load them inside your trainable
from disk (making sure that all nodes have access to the files) or cloud storage.
See :ref:`tune-bottlenecks` for more information.
For a high-level overview, see this example:
.. TODO: test this
.. code-block :: python
config = {
# Sample a float uniformly between -5.0 and -1.0
"uniform": tune.uniform(-5, -1),
# Sample a float uniformly between 3.2 and 5.4,
# rounding to multiples of 0.2
"quniform": tune.quniform(3.2, 5.4, 0.2),
# Sample a float uniformly between 0.0001 and 0.01, while
# sampling in log space
"loguniform": tune.loguniform(1e-4, 1e-2),
# Sample a float uniformly between 0.0001 and 0.1, while
# sampling in log space and rounding to multiples of 0.00005
"qloguniform": tune.qloguniform(1e-4, 1e-1, 5e-5),
# Sample a random float from a normal distribution with
# mean=10 and sd=2
"randn": tune.randn(10, 2),
# Sample a random float from a normal distribution with
# mean=10 and sd=2, rounding to multiples of 0.2
"qrandn": tune.qrandn(10, 2, 0.2),
# Sample a integer uniformly between -9 (inclusive) and 15 (exclusive)
"randint": tune.randint(-9, 15),
# Sample a random uniformly between -21 (inclusive) and 12 (inclusive (!))
# rounding to multiples of 3 (includes 12)
# if q is 1, then randint is called instead with the upper bound exclusive
"qrandint": tune.qrandint(-21, 12, 3),
# Sample a integer uniformly between 1 (inclusive) and 10 (exclusive),
# while sampling in log space
"lograndint": tune.lograndint(1, 10),
# Sample a integer uniformly between 1 (inclusive) and 10 (inclusive (!)),
# while sampling in log space and rounding to multiples of 2
# if q is 1, then lograndint is called instead with the upper bound exclusive
"qlograndint": tune.qlograndint(1, 10, 2),
# Sample an option uniformly from the specified choices
"choice": tune.choice(["a", "b", "c"]),
# Sample from a random function, in this case one that
# depends on another value from the search space
"func": tune.sample_from(lambda config: config["uniform"] * 0.01),
# Do a grid search over these values. Every value will be sampled
# ``num_samples`` times (``num_samples`` is the parameter you pass to ``tune.TuneConfig``,
# which is taken in by ``Tuner``)
"grid": tune.grid_search([32, 64, 128])
}
.. currentmodule:: ray
Random Distributions API
------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
tune.uniform
tune.quniform
tune.loguniform
tune.qloguniform
tune.randn
tune.qrandn
tune.randint
tune.qrandint
tune.lograndint
tune.qlograndint
tune.choice
Grid Search and Custom Function APIs
------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
tune.grid_search
tune.sample_from
References
----------
See also :ref:`tune-basicvariant`.
doc/source/tune/api/stoppers.rst
+50
View File
@@ -0,0 +1,50 @@
.. _tune-stoppers:
Tune Stopping Mechanisms (tune.stopper)
=======================================
In addition to Trial Schedulers like :ref:`ASHA <tune-scheduler-hyperband>`, where a number of
trials are stopped if they perform subpar, Ray Tune also supports custom stopping mechanisms to stop trials early. They can also stop the entire experiment after a condition is met.
For instance, stopping mechanisms can specify to stop trials when they reached a plateau and the metric
doesn't change anymore.
Ray Tune comes with several stopping mechanisms out of the box. For custom stopping behavior, you can
inherit from the :class:`Stopper <ray.tune.Stopper>` class.
Other stopping behaviors are described :ref:`in the user guide <tune-stopping-ref>`.
.. _tune-stop-ref:
Stopper Interface (tune.Stopper)
--------------------------------
.. currentmodule:: ray.tune.stopper
.. autosummary::
:nosignatures:
:toctree: doc/
Stopper
.. autosummary::
:nosignatures:
:toctree: doc/
Stopper.__call__
Stopper.stop_all
Tune Built-in Stoppers
----------------------
.. autosummary::
:nosignatures:
:toctree: doc/
MaximumIterationStopper
ExperimentPlateauStopper
TrialPlateauStopper
TimeoutStopper
CombinedStopper
~function_stopper.FunctionStopper
~noop.NoopStopper
doc/source/tune/api/suggestion.rst
+295
View File
@@ -0,0 +1,295 @@
.. _tune-search-alg:
Tune Search Algorithms (tune.search)
====================================
Tune's Search Algorithms are wrappers around open-source optimization libraries for efficient hyperparameter selection.
Each library has a specific way of defining the search space - please refer to their documentation for more details.
Tune will automatically convert search spaces passed to ``Tuner`` to the library format in most cases.
You can utilize these search algorithms as follows:
.. code-block:: python
from ray import tune
from ray.tune.search.optuna import OptunaSearch
def train_fn(config):
# This objective function is just for demonstration purposes
tune.report({"loss": config["param"]})
tuner = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(
search_alg=OptunaSearch(),
num_samples=100,
metric="loss",
mode="min",
),
param_space={"param": tune.uniform(0, 1)},
)
results = tuner.fit()
Saving and Restoring Tune Search Algorithms
-------------------------------------------
.. TODO: what to do about this section? It doesn't really belong here and is not worth its own guide.
.. TODO: at least check that this pseudo-code runs.
Certain search algorithms have ``save/restore`` implemented,
allowing reuse of searchers that are fitted on the results of multiple tuning runs.
.. code-block:: python
search_alg = HyperOptSearch()
tuner_1 = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(search_alg=search_alg)
)
results_1 = tuner_1.fit()
search_alg.save("./my-checkpoint.pkl")
# Restore the saved state onto another search algorithm,
# in a new tuning script
search_alg2 = HyperOptSearch()
search_alg2.restore("./my-checkpoint.pkl")
tuner_2 = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(search_alg=search_alg2)
)
results_2 = tuner_2.fit()
Tune automatically saves searcher state inside the current experiment folder during tuning.
See ``Result logdir: ...`` in the output logs for this location.
Note that if you have two Tune runs with the same experiment folder,
the previous state checkpoint will be overwritten. You can
avoid this by making sure ``RunConfig(name=...)`` is set to a unique
identifier:
.. code-block:: python
search_alg = HyperOptSearch()
tuner_1 = tune.Tuner(
train_fn,
tune_config=tune.TuneConfig(
num_samples=5,
search_alg=search_alg,
),
run_config=tune.RunConfig(
name="my-experiment-1",
storage_path="~/my_results",
)
)
results = tuner_1.fit()
search_alg2 = HyperOptSearch()
search_alg2.restore_from_dir(
os.path.join("~/my_results", "my-experiment-1")
)
.. _tune-basicvariant:
Random search and grid search (tune.search.basic_variant.BasicVariantGenerator)
-------------------------------------------------------------------------------
The default and most basic way to do hyperparameter search is via random and grid search.
Ray Tune does this through the :class:`BasicVariantGenerator <ray.tune.search.basic_variant.BasicVariantGenerator>`
class that generates trial variants given a search space definition.
The :class:`BasicVariantGenerator <ray.tune.search.basic_variant.BasicVariantGenerator>` is used per
default if no search algorithm is passed to
:func:`Tuner <ray.tune.Tuner>`.
.. currentmodule:: ray.tune.search
.. autosummary::
:nosignatures:
:toctree: doc/
basic_variant.BasicVariantGenerator
.. _tune-ax:
Ax (tune.search.ax.AxSearch)
----------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
ax.AxSearch
.. _bayesopt:
Bayesian Optimization (tune.search.bayesopt.BayesOptSearch)
-----------------------------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
bayesopt.BayesOptSearch
.. _suggest-TuneBOHB:
BOHB (tune.search.bohb.TuneBOHB)
--------------------------------
BOHB (Bayesian Optimization HyperBand) is an algorithm that both terminates bad trials
and also uses Bayesian Optimization to improve the hyperparameter search.
It is available from the `HpBandSter library <https://github.com/automl/HpBandSter>`_.
Importantly, BOHB is intended to be paired with a specific scheduler class: :ref:`HyperBandForBOHB <tune-scheduler-bohb>`.
In order to use this search algorithm, you will need to install ``HpBandSter`` and ``ConfigSpace``:
.. code-block:: bash
$ pip install hpbandster ConfigSpace
See the `BOHB paper <https://arxiv.org/abs/1807.01774>`_ for more details.
.. autosummary::
:nosignatures:
:toctree: doc/
bohb.TuneBOHB
.. _tune-hebo:
HEBO (tune.search.hebo.HEBOSearch)
----------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
hebo.HEBOSearch
.. _tune-hyperopt:
HyperOpt (tune.search.hyperopt.HyperOptSearch)
----------------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
hyperopt.HyperOptSearch
.. _nevergrad:
Nevergrad (tune.search.nevergrad.NevergradSearch)
-------------------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
nevergrad.NevergradSearch
.. _tune-optuna:
Optuna (tune.search.optuna.OptunaSearch)
----------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
optuna.OptunaSearch
.. _zoopt:
ZOOpt (tune.search.zoopt.ZOOptSearch)
-------------------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
zoopt.ZOOptSearch
.. _repeater:
Repeated Evaluations (tune.search.Repeater)
-------------------------------------------
Use ``ray.tune.search.Repeater`` to average over multiple evaluations of the same
hyperparameter configurations. This is useful in cases where the evaluated
training procedure has high variance (i.e., in reinforcement learning).
By default, ``Repeater`` will take in a ``repeat`` parameter and a ``search_alg``.
The ``search_alg`` will suggest new configurations to try, and the ``Repeater``
will run ``repeat`` trials of the configuration. It will then average the
``search_alg.metric`` from the final results of each repeated trial.
.. warning:: It is recommended to not use ``Repeater`` with a TrialScheduler.
Early termination can negatively affect the average reported metric.
.. autosummary::
:nosignatures:
:toctree: doc/
Repeater
.. _limiter:
ConcurrencyLimiter (tune.search.ConcurrencyLimiter)
---------------------------------------------------
Use ``ray.tune.search.ConcurrencyLimiter`` to limit the amount of concurrency when using a search algorithm.
This is useful when a given optimization algorithm does not parallelize very well (like a naive Bayesian Optimization).
.. autosummary::
:nosignatures:
:toctree: doc/
ConcurrencyLimiter
.. _byo-algo:
Custom Search Algorithms (tune.search.Searcher)
-----------------------------------------------
If you are interested in implementing or contributing a new Search Algorithm, provide the following interface:
.. autosummary::
:nosignatures:
:toctree: doc/
Searcher
.. autosummary::
:nosignatures:
:toctree: doc/
Searcher.suggest
Searcher.save
Searcher.restore
Searcher.on_trial_result
Searcher.on_trial_complete
If contributing, make sure to add test cases and an entry in the function described below.
.. _shim:
Shim Instantiation (tune.create_searcher)
-----------------------------------------
There is also a shim function that constructs the search algorithm based on the provided string.
This can be useful if the search algorithm you want to use changes often
(e.g., specifying the search algorithm via a CLI option or config file).
.. autosummary::
:nosignatures:
:toctree: doc/
create_searcher
doc/source/tune/api/syncing.rst
+18
View File
@@ -0,0 +1,18 @@
Syncing in Tune
===============
.. seealso::
See :doc:`this user guide </tune/tutorials/tune-storage>` for more details and examples.
.. _tune-sync-config:
Tune Syncing Configuration
--------------------------
.. autosummary::
:nosignatures:
:toctree: doc/
~ray.tune.SyncConfig
doc/source/tune/api/trainable.rst
+311
View File
@@ -0,0 +1,311 @@
.. _trainable-docs:
.. TODO: these "basic" sections before the actual API docs start don't really belong here. Then again, the function
API does not really have a signature to just describe.
.. TODO: Reusing actors and advanced resources allocation seem ill-placed.
Training in Tune (tune.Trainable, tune.report)
=================================================
Training can be done with either a **Function API** (:func:`tune.report() <ray.tune.report>`) or
**Class API** (:ref:`tune.Trainable <tune-trainable-docstring>`).
For the sake of example, let's maximize this objective function:
.. literalinclude:: /tune/doc_code/trainable.py
:language: python
:start-after: __example_objective_start__
:end-before: __example_objective_end__
.. _tune-function-api:
Function Trainable API
----------------------
Use the Function API to define a custom training function that Tune runs in Ray actor processes. Each trial is placed
into a Ray actor process and runs in parallel.
The ``config`` argument in the function is a dictionary populated automatically by Ray Tune and corresponding to
the hyperparameters selected for the trial from the :ref:`search space <tune-key-concepts-search-spaces>`.
With the Function API, you can report intermediate metrics by simply calling :func:`tune.report() <ray.tune.report>` within the function.
.. literalinclude:: /tune/doc_code/trainable.py
:language: python
:start-after: __function_api_report_intermediate_metrics_start__
:end-before: __function_api_report_intermediate_metrics_end__
.. tip:: Do not use :func:`tune.report() <ray.tune.report>` within a ``Trainable`` class.
In the previous example, we reported on every step, but this metric reporting frequency
is configurable. For example, we could also report only a single time at the end with the final score:
.. literalinclude:: /tune/doc_code/trainable.py
:language: python
:start-after: __function_api_report_final_metrics_start__
:end-before: __function_api_report_final_metrics_end__
It's also possible to return a final set of metrics to Tune by returning them from your function:
.. literalinclude:: /tune/doc_code/trainable.py
:language: python
:start-after: __function_api_return_final_metrics_start__
:end-before: __function_api_return_final_metrics_end__
Note that Ray Tune outputs extra values in addition to the user reported metrics,
such as ``iterations_since_restore``. See :ref:`tune-autofilled-metrics` for an explanation of these values.
See how to configure checkpointing for a function trainable :ref:`here <tune-function-trainable-checkpointing>`.
.. _tune-class-api:
Class Trainable API
--------------------------
.. caution:: Do not use :func:`tune.report() <ray.tune.report>` within a ``Trainable`` class.
The Trainable **class API** will require users to subclass ``ray.tune.Trainable``. Here's a naive example of this API:
.. literalinclude:: /tune/doc_code/trainable.py
:language: python
:start-after: __class_api_example_start__
:end-before: __class_api_example_end__
As a subclass of ``tune.Trainable``, Tune will create a ``Trainable`` object on a
separate process (using the :ref:`Ray Actor API <actor-guide>`).
1. ``setup`` function is invoked once training starts.
2. ``step`` is invoked **multiple times**.
Each time, the Trainable object executes one logical iteration of training in the tuning process,
which may include one or more iterations of actual training.
3. ``cleanup`` is invoked when training is finished.
The ``config`` argument in the ``setup`` method is a dictionary populated automatically by Tune and corresponding to
the hyperparameters selected for the trial from the :ref:`search space <tune-key-concepts-search-spaces>`.
.. tip:: As a rule of thumb, the execution time of ``step`` should be large enough to avoid overheads
(i.e. more than a few seconds), but short enough to report progress periodically (i.e. at most a few minutes).
You'll notice that Ray Tune will output extra values in addition to the user reported metrics,
such as ``iterations_since_restore``.
See :ref:`tune-autofilled-metrics` for an explanation/glossary of these values.
See how to configure checkpoint for class trainable :ref:`here <tune-class-trainable-checkpointing>`.
Advanced: Reusing Actors in Tune
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note:: This feature is only for the Trainable Class API.
Your Trainable can often take a long time to start.
To avoid this, you can do ``tune.TuneConfig(reuse_actors=True)`` (which is taken in by ``Tuner``) to reuse the same Trainable Python process and
object for multiple hyperparameters.
This requires you to implement ``Trainable.reset_config``, which provides a new set of hyperparameters.
It is up to the user to correctly update the hyperparameters of your trainable.
.. code-block:: python
from time import sleep
import ray
from ray import tune
from ray.tune.tuner import Tuner
def expensive_setup():
print("EXPENSIVE SETUP")
sleep(1)
class QuadraticTrainable(tune.Trainable):
def setup(self, config):
self.config = config
expensive_setup() # use reuse_actors=True to only run this once
self.max_steps = 5
self.step_count = 0
def step(self):
# Extract hyperparameters from the config
h1 = self.config["hparam1"]
h2 = self.config["hparam2"]
# Compute a simple quadratic objective where the optimum is at hparam1=3 and hparam2=5
loss = (h1 - 3) ** 2 + (h2 - 5) ** 2
metrics = {"loss": loss}
self.step_count += 1
if self.step_count > self.max_steps:
metrics["done"] = True
# Return the computed loss as the metric
return metrics
def reset_config(self, new_config):
# Update the configuration for a new trial while reusing the actor
self.config = new_config
return True
ray.init()
tuner_with_reuse = Tuner(
QuadraticTrainable,
param_space={
"hparam1": tune.uniform(-10, 10),
"hparam2": tune.uniform(-10, 10),
},
tune_config=tune.TuneConfig(
num_samples=10,
max_concurrent_trials=1,
reuse_actors=True, # Enable actor reuse and avoid expensive setup
),
run_config=ray.tune.RunConfig(
verbose=0,
checkpoint_config=ray.tune.CheckpointConfig(checkpoint_at_end=False),
),
)
tuner_with_reuse.fit()
Comparing Tune's Function API and Class API
-------------------------------------------
Here are a few key concepts and what they look like for the Function and Class API's.
======================= =============================================== ==============================================
Concept Function API Class API
======================= =============================================== ==============================================
Training Iteration Increments on each `tune.report` call Increments on each `Trainable.step` call
Report metrics `tune.report(metrics)` Return metrics from `Trainable.step`
Saving a checkpoint `tune.report(..., checkpoint=checkpoint)` `Trainable.save_checkpoint`
Loading a checkpoint `tune.get_checkpoint()` `Trainable.load_checkpoint`
Accessing config Passed as an argument `def train_func(config):` Passed through `Trainable.setup`
======================= =============================================== ==============================================
Advanced Resource Allocation
----------------------------
Trainables can themselves be distributed. If your trainable function / class creates further Ray actors or tasks
that also consume CPU / GPU resources, you will want to add more bundles to the :class:`PlacementGroupFactory`
to reserve extra resource slots.
For example, if a trainable class requires 1 GPU itself, but also launches 4 actors, each using another GPU,
then you should use :func:`tune.with_resources <ray.tune.with_resources>` like this:
.. code-block:: python
:emphasize-lines: 4-10
tuner = tune.Tuner(
tune.with_resources(my_trainable, tune.PlacementGroupFactory([
{"CPU": 1, "GPU": 1},
{"GPU": 1},
{"GPU": 1},
{"GPU": 1},
{"GPU": 1}
])),
run_config=RunConfig(name="my_trainable")
)
The ``Trainable`` also provides the ``default_resource_requests`` interface to automatically
declare the resources per trial based on the given configuration.
It is also possible to specify memory (``"memory"``, in bytes) and custom resource requirements.
.. currentmodule:: ray
Function API
------------
For reporting results and checkpoints with the function API,
see the :ref:`Ray Train utilities <train-loop-api>` documentation.
**Classes**
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.Checkpoint
~tune.TuneContext
**Functions**
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.get_checkpoint
~tune.get_context
~tune.report
.. _tune-trainable-docstring:
Trainable (Class API)
---------------------
Constructor
~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.Trainable
Trainable Methods to Implement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
~tune.Trainable.setup
~tune.Trainable.save_checkpoint
~tune.Trainable.load_checkpoint
~tune.Trainable.step
~tune.Trainable.reset_config
~tune.Trainable.cleanup
~tune.Trainable.default_resource_request
.. _tune-util-ref:
Tune Trainable Utilities
-------------------------
Tune Data Ingestion Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
tune.with_parameters
Tune Resource Assignment Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
tune.with_resources
~tune.execution.placement_groups.PlacementGroupFactory
tune.utils.wait_for_gpu
Tune Trainable Debugging Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:nosignatures:
:toctree: doc/
tune.utils.diagnose_serialization
tune.utils.validate_save_restore
tune.utils.util.validate_warmstart