wassname/ray
1
0
Fork 0
mirror of https://github.com/wassname/ray.git synced 2026-07-21 12:50:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

[tune] Update API Reference Page (#7671)

Browse Source 
* widerdocs

* init

* docs

* fix

* moveit

* mix

* better_docs

* remove

* Apply suggestions from code review

Co-Authored-By: Sven Mika <sven@anyscale.io>

Co-authored-by: Sven Mika <sven@anyscale.io>
This commit is contained in:
Richard Liaw
2020-03-22 16:42:20 -07:00
committed by GitHub
co-authored by Sven Mika
parent 288933ec6b
commit 81d311031b
27 changed files with 744 additions and 394 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/Makefile
+1 -1
View File
@@ -2,7 +2,7 @@
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
doc/source/_static/css/custom.css
+21
View File
@@ -0,0 +1,21 @@
/* Max window size */
.wy-nav-content{
max-width: 1000px;
}
/*Extends the docstring signature box.*/
.rst-content dl:not(.docutils) dt {
display: block;
padding: 10px;
word-wrap: break-word;
padding-right: 100px;
}
/*Lists in an admonition note do not have awkward whitespace below.*/
.rst-content .admonition-note .section ul {
margin-bottom: 0px
}
/*Properties become blue (classmethod, staticmethod, property)*/
.rst-content dl dt em.property {
color: #2980B9;
text-transform: uppercase
}
doc/source/conf.py
+10 -29
View File
@@ -23,35 +23,15 @@ from custom_directives import CustomGalleryItemDirective
# These lines added to enable Sphinx to work without installing Ray.
import mock
MOCK_MODULES = [
"blist",
"gym",
"gym.spaces",
"ray._raylet",
"ray.core.generated",
"ray.core.generated.gcs_pb2",
"ray.core.generated.ray.protocol.Task",
"scipy",
"scipy.signal",
"scipy.stats",
"tensorflow_probability",
"tensorflow",
"tensorflow.contrib",
"tensorflow.contrib.all_reduce",
"tensorflow.contrib.all_reduce.python",
"tensorflow.contrib.layers",
"tensorflow.contrib.rnn",
"tensorflow.contrib.slim",
"tensorflow.core",
"tensorflow.core.util",
"tensorflow.python",
"tensorflow.python.client",
"tensorflow.python.util",
"torch",
"torch.distributed",
"torch.nn",
"torch.nn.parallel",
"torch.utils.data",
"torch.utils.data.distributed"
"blist", "gym", "gym.spaces", "ray._raylet", "ray.core.generated",
"ray.core.generated.gcs_pb2", "ray.core.generated.ray.protocol.Task",
"scipy", "scipy.signal", "scipy.stats", "tensorflow_probability",
"tensorflow", "tensorflow.contrib", "tensorflow.contrib.all_reduce",
"tensorflow.contrib.all_reduce.python", "tensorflow.contrib.layers",
"tensorflow.contrib.rnn", "tensorflow.contrib.slim", "tensorflow.core",
"tensorflow.core.util", "tensorflow.python", "tensorflow.python.client",
"tensorflow.python.util", "torch", "torch.distributed", "torch.nn",
"torch.nn.parallel", "torch.utils.data", "torch.utils.data.distributed"
]
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = mock.Mock()
@@ -394,5 +374,6 @@ def update_context(app, pagename, templatename, context, doctree):
def setup(app):
app.connect('html-page-context', update_context)
app.add_stylesheet('css/custom.css')
# Custom directives
app.add_directive('customgalleryitem', CustomGalleryItemDirective)
doc/source/development.rst
+41 -16
View File
@@ -1,8 +1,8 @@
Development Tips
================
**Note:** Unless otherwise stated, directory and file paths are relative to the
project root directory.
.. note:: Unless otherwise stated, directory and file paths are relative to the project root directory.
Compilation
-----------
@@ -25,9 +25,9 @@ If you run into **Permission Denied** errors when running ``pip install``,
you can try adding ``--user``. You may also need to run something like ``sudo
chown -R $USER $HOME/anaconda3`` (substituting in the appropriate path).
If you make changes to the C++ or Python files, you will need to run the
build so C++ code is recompiled and/or Python files are redeployed in
the ``python`` directory. However, you do not need to rerun
If you make changes to the C++ or Python files, you will need to run the
build so C++ code is recompiled and/or Python files are redeployed in
the ``python`` directory. However, you do not need to rerun
``pip install -e .``. Instead, you can recompile much more quickly by running
the following:
@@ -38,6 +38,31 @@ the following:
This command is not enough to recompile all C++ unit tests. To do so, see
`Testing locally`_.
.. _python-develop:
Developing Ray (Python Only)
----------------------------
.. note:: Unless otherwise stated, directory and file paths are relative to the project root directory.
RLlib, Tune, Autoscaler, and most Python files do not require you to build and compile Ray. Follow these instructions to develop Ray's Python files locally.
1. Pip install the **latest Ray wheels.** See :ref:`install-nightlies` for instructions.
2. Fork and clone the project to your machine. Connect your repository to the upstream (main project) ray repository.
.. code-block:: shell
git clone https://github.com/[your username]/ray.git
cd ray
git remote add upstream https://github.com/ray-project/ray.git
# Make sure you are up-to-date on master.
4. Run ``python python/ray/setup-dev.py``. This sets up links between the ``tune`` dir (among other directories) in your local repo and the one bundled with the ``ray`` package.
.. warning:: Do not run ``pip uninstall ray`` or ``pip install -U`` (for Ray or Ray wheels) if setting up your environment this way. To uninstall or upgrade, you must ``rm -rf`` the installation site (usually a ``site-packages/ray`` location).
Using a local repository for dependencies
-----------------------------------------
@@ -165,7 +190,7 @@ Testing locally
Testing for Python development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Suppose that one of the tests in a file of tests, e.g.,
Suppose that one of the tests in a file of tests, e.g.,
``python/ray/tests/test_basic.py``, is failing. You can run just that
test file locally as follows:
@@ -204,7 +229,7 @@ Alternatively, you can also run one specific C++ test. You can use:
Building the Docs
-----------------
If you make changes that require documentation changes, don't forget to
If you make changes that require documentation changes, don't forget to
update the documentation!
When you make documentation changes, build them locally to verify they render
@@ -213,13 +238,13 @@ correctly. `Sphinx <http://sphinx-doc.org/>`_ is used to generate the documentat
.. code-block:: shell
cd doc
pip install -r requirements-doc.txt
pip install -r requirements-doc.txt
make html
Once done, the docs will be in ``doc/_build/html``. For example, on Mac
OSX, you can open the docs (assuming you are still in the ``doc``
Once done, the docs will be in ``doc/_build/html``. For example, on Mac
OSX, you can open the docs (assuming you are still in the ``doc``
directory) using ``open _build/html/index.html``.
Creating a pull request
-----------------------
@@ -227,7 +252,7 @@ Creating a pull request
To create a pull request (PR) for your change, first go through the
`PR template`_ checklist and ensure you've completed all the steps.
When you push changes to GitHub, the formatting and verification script
When you push changes to GitHub, the formatting and verification script
``ci/travis/format.sh`` is run first. For pushing to your fork, you can
skip this step with ``git push --no-verify``.
@@ -243,7 +268,7 @@ of the following tools. Installation commands are shown for convenience:
**Note:** On MacOS X, don't use HomeBrew to install ``clang-format``, as the only version available is too new.
The Ray project automatically runs continuous integration (CI) tests once a PR
is opened using `Travis-CI <https://travis-ci.com/ray-project/ray/>`_ with
is opened using `Travis-CI <https://travis-ci.com/ray-project/ray/>`_ with
multiple CI test jobs.
@@ -266,7 +291,7 @@ scripts. Some of the examples include:
* ``python python/ray/serve/examples/echo_full.py``
If a Travis-CI build exception doesn't appear to be related to your change,
please visit `this link <https://ray-travis-tracker.herokuapp.com/>`_ to
please visit `this link <https://ray-travis-tracker.herokuapp.com/>`_ to
check recent tests known to be flaky.
@@ -277,11 +302,11 @@ Installation instructions for the tools mentioned here are discussed above in
`Creating a pull request`_.
**Running the linter locally:** To run the Python linter on a specific file, run
``flake8`` as in this example, ``flake8 python/ray/worker.py``.
``flake8`` as in this example, ``flake8 python/ray/worker.py``.
**Autoformatting code**. We use `yapf <https://github.com/google/yapf>`_ for
linting. The config file is ``.style.yapf``. We recommend running
``scripts/yapf.sh`` prior to pushing a PR to format any changed files. Note
``scripts/yapf.sh`` prior to pushing a PR to format any changed files. Note
that some projects, such as dataframes and rllib, are currently excluded.
**Running CI linter:** The Travis CI linter script has multiple components to
doc/source/tune-contrib.rst
+23 -45
View File
@@ -11,48 +11,12 @@ We welcome (and encourage!) all forms of contributions to Tune, including and no
- Test cases to make the codebase more robust.
- Tutorials, blog posts, talks that promote the project.
Developing Tune
---------------
Setting up a development environment
------------------------------------
If you have Ray installed via pip (``pip install -U [link to wheel]`` - you can find the link to the latest wheel `here <https://ray.readthedocs.io/en/latest/installation.html>`__), you can develop Tune locally without needing to compile Ray.
First, you will need your own `fork <https://help.github.com/en/articles/fork-a-repo>`__ to work on the code. Press the Fork button on the `ray project page <https://github.com/ray-project/ray/>`__.
Then, clone the project to your machine and connect your repository to the upstream (main project) ray repository.
.. code-block:: shell
git clone https://github.com/[your username]/ray.git [path to ray directory]
cd [path to ray directory]
git remote add upstream https://github.com/ray-project/ray.git
Before continuing, make sure that your git branch is in sync with the installed Ray binaries (i.e., you are up-to-date on `master <https://github.com/ray-project/ray>`__ and have the latest `wheel <https://ray.readthedocs.io/en/latest/installation.html>`__ installed.)
Then, run `[path to ray directory]/python/ray/setup-dev.py` `(also here on Github) <https://github.com/ray-project/ray/blob/master/python/ray/setup-dev.py>`__ script.
This sets up links between the ``tune`` dir (among other directories) in your local repo and the one bundled with the ``ray`` package.
As a last step make sure to install all packages required for development of tune. This can be done by running:
.. code-block:: shell
pip install -r [path to ray directory]/python/ray/tune/requirements-dev.txt
What can I work on?
-------------------
We use Github to track issues, feature requests, and bugs. Take a look at the
ones labeled `"good first issue" <https://github.com/ray-project/ray/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`__ and `"help wanted" <https://github.com/ray-project/ray/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`__ for a place to start. Look for issues with "[tune]" in the title.
.. note::
If raising a new issue or PR related to Tune, be sure to include "[tune]" in the beginning of the title.
For project organization, Tune maintains a relatively up-to-date organization of
issues on the `Tune Github Project Board <https://github.com/ray-project/ray/projects/4>`__.
Here, you can track and identify how issues are organized.
First, following the instructions in :ref:`python-develop` to develop Tune without compiling Ray.
After Ray is set up, run ``pip install -r ray/python/ray/tune/requirements-dev.txt`` to install all packages required for Tune development.
Submitting and Merging a Contribution
-------------------------------------
@@ -65,12 +29,12 @@ There are a couple steps to merge a contribution.
git remote add upstream https://github.com/ray-project/ray.git
git fetch upstream
git rebase upstream/master
git rebase upstream/master # or git pull . upstream/master
2. Make sure all existing tests `pass <tune-contrib.html#testing>`__.
3. If introducing a new feature or patching a bug, be sure to add new test cases
in the relevant file in `tune/tests/`.
4. Document the code. Public functions need to be documented, and remember to provide an usage
in the relevant file in ``tune/tests/``.
4. Document the code. Public functions need to be documented, and remember to provide a usage
example if applicable.
5. Request code reviews from other contributors and address their comments. One fast way to get reviews is
to help review others' code so that they return the favor. You should aim to improve the code as much as
@@ -93,14 +57,28 @@ burden and speedup review process.
Documentation should be documented in `Google style <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__ format.
We also have tests for code formatting and linting that need to pass before merge.
Install `yapf==0.23, flake8, flake8-quotes` (these are also in the `requirements-dev.txt` found in ``python/ray/tune``). You can run the following locally:
We also have tests for code formatting and linting that need to pass before merge. You can run the following locally:
.. code-block:: shell
ray/scripts/format.sh
What can I work on?
-------------------
We use Github to track issues, feature requests, and bugs. Take a look at the
ones labeled `"good first issue" <https://github.com/ray-project/ray/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`__ and `"help wanted" <https://github.com/ray-project/ray/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`__ for a place to start. Look for issues with "[tune]" in the title.
.. note::
If raising a new issue or PR related to Tune, be sure to include "[tune]" in the title and add a ``tune`` label.
For project organization, Tune maintains a relatively up-to-date organization of
issues on the `Tune Github Project Board <https://github.com/ray-project/ray/projects/4>`__.
Here, you can track and identify how issues are organized.
Becoming a Reviewer
-------------------
doc/source/tune-package-ref.rst
+274 -26
View File
@@ -1,54 +1,302 @@
Tune Package Reference
=======================
ray.tune
--------
Training (tune.run, tune.Experiment)
------------------------------------
.. automodule:: ray.tune
:members:
:show-inheritance:
:exclude-members: TuneError, Trainable, DurableTrainable
tune.run
~~~~~~~~
.. autofunction:: ray.tune.run
tune.run_experiments
~~~~~~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.run_experiments
tune.Experiment
~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.Experiment
Trainable (tune.Trainable, tune.track)
--------------------------------------
tune.Trainable
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.Trainable
:members:
:member-order: groupwise
:private-members:
:members:
tune.DurableTrainable
~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.DurableTrainable
tune.track
~~~~~~~~~~
.. automodule:: ray.tune.track
:members:
:exclude-members: init, shutdown
StatusReporter
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.function_runner.StatusReporter
:members: __call__, logdir
ray.tune.schedulers
-------------------
Sampling (tune.rand, tune.grid_search...)
-----------------------------------------
.. automodule:: ray.tune.schedulers
:members:
tune.randn
~~~~~~~~~~
.. autofunction:: ray.tune.randn
tune.loguniform
~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.loguniform
tune.uniform
~~~~~~~~~~~~
.. autofunction:: ray.tune.uniform
tune.choice
~~~~~~~~~~~
.. autofunction:: ray.tune.choice
tune.sample_from
~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.sample_from
tune.grid_search
~~~~~~~~~~~~~~~~
.. autofunction:: ray.tune.grid_search
Stopper (tune.Stopper)
----------------------
.. autoclass:: ray.tune.Stopper
:members: __call__, stop_all
Analysis (tune.analysis)
------------------------
ExperimentAnalysis
~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.ExperimentAnalysis
:show-inheritance:
ray.tune.suggest
----------------
.. automodule:: ray.tune.suggest
:members:
:exclude-members: function, sample_from, grid_search, SuggestionAlgorithm
:show-inheritance:
Analysis
~~~~~~~~
.. autoclass:: ray.tune.Analysis
:members:
Schedulers (tune.schedulers)
----------------------------
FIFOScheduler
~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.FIFOScheduler
HyperBandScheduler
~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.HyperBandScheduler
ASHAScheduler/AsyncHyperBandScheduler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.AsyncHyperBandScheduler
.. autoclass:: ray.tune.schedulers.ASHAScheduler
MedianStoppingRule
~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.MedianStoppingRule
PopulationBasedTraining
~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.PopulationBasedTraining
TrialScheduler
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.schedulers.TrialScheduler
:members:
Search Algorithms (tune.suggest)
--------------------------------
BasicVariantGenerator
~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.BasicVariantGenerator
AxSearch
~~~~~~~~
.. autoclass:: ray.tune.suggest.ax.AxSearch
BayesOptSearch
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.bayesopt.BayesOptSearch
TuneBOHB
~~~~~~~~
.. autoclass:: ray.tune.suggest.bohb.TuneBOHB
DragonflySearch
~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.dragonfly.DragonflySearch
HyperOptSearch
~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.hyperopt.HyperOptSearch
NevergradSearch
~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.nevergrad.NevergradSearch
SigOptSearch
~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.sigopt.SigOptSearch
SkOptSearch
~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.skopt.SkOptSearch
SearchAlgorithm
~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.SearchAlgorithm
:members:
SuggestionAlgorithm
~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.suggest.SuggestionAlgorithm
:members:
:private-members:
:show-inheritance:
Repeater
~~~~~~~~
.. autoclass:: ray.tune.suggest.Repeater
ray.tune.track
--------------
Loggers (tune.logger)
---------------------
.. automodule:: ray.tune.track
:members:
ray.tune.logger
---------------
Logger
~~~~~~
.. autoclass:: ray.tune.logger.Logger
UnifiedLogger
~~~~~~~~~~~~~
.. autoclass:: ray.tune.logger.UnifiedLogger
TBXLogger
~~~~~~~~~
.. autoclass:: ray.tune.logger.TBXLogger
JsonLogger
~~~~~~~~~~
.. autoclass:: ray.tune.logger.JsonLogger
CSVLogger
~~~~~~~~~
.. autoclass:: ray.tune.logger.CSVLogger
MLFLowLogger
~~~~~~~~~~~~
.. autoclass:: ray.tune.logger.MLFLowLogger
Reporters
---------
ProgressReporter
~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.ProgressReporter
:members:
CLIReporter
~~~~~~~~~~~
.. autoclass:: ray.tune.CLIReporter
JupyterNotebookReporter
~~~~~~~~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.JupyterNotebookReporter
Internals
---------
Registry
~~~~~~~~
.. autofunction:: ray.tune.register_trainable
.. autofunction:: ray.tune.register_env
RayTrialExecutor
~~~~~~~~~~~~~~~~
.. autoclass:: ray.tune.ray_trial_executor.RayTrialExecutor
:members:
TrialExecutor
~~~~~~~~~~~~~
.. autoclass:: ray.tune.trial_executor.TrialExecutor
:members:
TrialRunner
~~~~~~~~~~~
.. autoclass:: ray.tune.trial_runner.TrialRunner
Trial
~~~~~
.. autoclass:: ray.tune.trial.Trial
Resources
~~~~~~~~~
.. autoclass:: ray.tune.resources.Resources
python/ray/tune/analysis/experiment_analysis.py
+15 -11
View File
@@ -17,7 +17,10 @@ logger = logging.getLogger(__name__)
class Analysis:
"""Analyze all results from a directory of experiments."""
"""Analyze all results from a directory of experiments.
To use this class, the experiment must be executed with the JsonLogger.
"""
def __init__(self, experiment_dir):
experiment_dir = os.path.expanduser(experiment_dir)
@@ -42,6 +45,9 @@ class Analysis:
metric (str): Key for trial info to order on.
If None, uses last result.
mode (str): One of [min, max].
Returns:
pd.DataFrame: Constructed from a result dict of each trial.
"""
rows = self._retrieve_rows(metric=metric, mode=mode)
all_configs = self.get_all_configs(prefix=True)
@@ -97,6 +103,9 @@ class Analysis:
Args:
prefix (bool): If True, flattens the config dict
and prepends `config/`.
Returns:
List[dict]: List of all configurations of trials,
"""
fail_count = 0
for path in self._get_trial_paths():
@@ -124,8 +133,7 @@ class Analysis:
"training_iteration" is used by default.
Returns:
A list of [path, metric] lists for all persistent checkpoints of
the trial.
List of [path, metric] for all persistent checkpoints of the trial.
"""
if isinstance(trial, str):
trial_dir = os.path.expanduser(trial)
@@ -177,10 +185,14 @@ class Analysis:
class ExperimentAnalysis(Analysis):
"""Analyze results from a Tune experiment.
To use this class, the experiment must be executed with the JsonLogger.
Parameters:
experiment_checkpoint_path (str): Path to a json file
representing an experiment state. Corresponds to
Experiment.local_dir/Experiment.name/experiment_state.json
trials (list|None): List of trials that can be accessed via
`analysis.trials`.
Example:
>>> tune.run(my_trainable, name="my_exp", local_dir="~/tune_results")
@@ -189,14 +201,6 @@ class ExperimentAnalysis(Analysis):
"""
def __init__(self, experiment_checkpoint_path, trials=None):
"""Initializer.
Args:
experiment_checkpoint_path (str): Path to where experiment is
located.
trials (list|None): List of trials that can be accessed via
`analysis.trials`.
"""
with open(experiment_checkpoint_path) as f:
_experiment_state = json.load(f)
self._experiment_state = _experiment_state
python/ray/tune/experiment.py
+21 -35
View File
@@ -48,25 +48,27 @@ def _raise_on_durable(trainable_name, sync_to_driver, upload_dir):
class Experiment:
"""Tracks experiment specifications.
Implicitly registers the Trainable if needed.
Implicitly registers the Trainable if needed. The args here take
the same meaning as the arguments defined `tune.py:run`.
Examples:
>>> experiment_spec = Experiment(
>>> "my_experiment_name",
>>> my_func,
>>> stop={"mean_accuracy": 100},
>>> config={
>>> "alpha": tune.grid_search([0.2, 0.4, 0.6]),
>>> "beta": tune.grid_search([1, 2]),
>>> },
>>> resources_per_trial={
>>> "cpu": 1,
>>> "gpu": 0
>>> },
>>> num_samples=10,
>>> local_dir="~/ray_results",
>>> checkpoint_freq=10,
>>> max_failures=2)
.. code-block:: python
experiment_spec = Experiment(
"my_experiment_name",
my_func,
stop={"mean_accuracy": 100},
config={
"alpha": tune.grid_search([0.2, 0.4, 0.6]),
"beta": tune.grid_search([1, 2]),
},
resources_per_trial={
"cpu": 1,
"gpu": 0
},
num_samples=10,
local_dir="~/ray_results",
checkpoint_freq=10,
max_failures=2)
"""
def __init__(self,
@@ -88,23 +90,7 @@ class Experiment:
checkpoint_score_attr=None,
export_formats=None,
max_failures=0,
restore=None,
repeat=None,
trial_resources=None,
sync_function=None):
"""Initialize a new Experiment.
The args here take the same meaning as the command line flags defined
in `tune.py:run`.
"""
if repeat:
_raise_deprecation_note("repeat", "num_samples", soft=False)
if trial_resources:
_raise_deprecation_note(
"trial_resources", "resources_per_trial", soft=False)
if sync_function:
_raise_deprecation_note(
"sync_function", "sync_to_driver", soft=False)
restore=None):
config = config or {}
self._run_identifier = Experiment.register_if_needed(run)
python/ray/tune/logger.py
+13
View File
@@ -31,6 +31,7 @@ class Logger:
Arguments:
config: Configuration passed to all logger creators.
logdir: Directory for all logger creators to log to.
trial (Trial): Trial object for the logger to access.
"""
def __init__(self, config, logdir, trial=None):
@@ -97,6 +98,13 @@ class MLFLowLogger(Logger):
class JsonLogger(Logger):
"""Logs trial results in json format.
Also writes to a results file and param.json file when results or
configurations are updated. Experiments must be executed with the
JsonLogger to be compatible with the ExperimentAnalysis tool.
"""
def _init(self):
self.update_config(self.config)
local_file = os.path.join(self.logdir, EXPR_RESULT_FILE)
@@ -278,6 +286,11 @@ class UnifiedLogger(Logger):
self._logger_cls_list = DEFAULT_LOGGERS
else:
self._logger_cls_list = loggers
if JsonLogger not in self._logger_cls_list:
if log_once("JsonLogger"):
logger.warning(
"JsonLogger not provided. The ExperimentAnalysis tool is "
"disabled.")
self._sync_function = sync_function
self._log_syncer = None
python/ray/tune/progress_reporter.py
+49 -51
View File
@@ -44,7 +44,22 @@ class ProgressReporter:
class TuneReporterBase(ProgressReporter):
"""Abstract base class for the default Tune reporters."""
"""Abstract base class for the default Tune reporters.
Args:
metric_columns (dict[str, str]|list[str]): Names of metrics to
include in progress table. If this is a dict, the keys should
be metric names and the values should be the displayed names.
If this is a list, the metric name is used directly.
max_progress_rows (int): Maximum number of rows to print
in the progress table. The progress table describes the
progress of each trial. Defaults to 20.
max_error_rows (int): Maximum number of rows to print in the
error table. The error table lists the error file, if any,
corresponding to each trial. Defaults to 20.
max_report_frequency (int): Maximum report frequency in seconds.
Defaults to 5s.
"""
# Truncated representations of column names (to accommodate small screens).
DEFAULT_COLUMNS = collections.OrderedDict({
@@ -61,22 +76,6 @@ class TuneReporterBase(ProgressReporter):
max_progress_rows=20,
max_error_rows=20,
max_report_frequency=5):
"""Initializes a new TuneReporterBase.
Args:
metric_columns (dict[str, str]|list[str]): Names of metrics to
include in progress table. If this is a dict, the keys should
be metric names and the values should be the displayed names.
If this is a list, the metric name is used directly.
max_progress_rows (int): Maximum number of rows to print
in the progress table. The progress table describes the
progress of each trial. Defaults to 20.
max_error_rows (int): Maximum number of rows to print in the
error table. The error table lists the error file, if any,
corresponding to each trial. Defaults to 20.
max_report_frequency (int): Maximum report frequency in seconds.
Defaults to 5s.
"""
self._metric_columns = metric_columns or self.DEFAULT_COLUMNS
self._max_progress_rows = max_progress_rows
self._max_error_rows = max_error_rows
@@ -145,7 +144,23 @@ class TuneReporterBase(ProgressReporter):
class JupyterNotebookReporter(TuneReporterBase):
"""Jupyter notebook-friendly Reporter that can update display in-place."""
"""Jupyter notebook-friendly Reporter that can update display in-place.
Args:
overwrite (bool): Flag for overwriting the last reported progress.
metric_columns (dict[str, str]|list[str]): Names of metrics to
include in progress table. If this is a dict, the keys should
be metric names and the values should be the displayed names.
If this is a list, the metric name is used directly.
max_progress_rows (int): Maximum number of rows to print
in the progress table. The progress table describes the
progress of each trial. Defaults to 20.
max_error_rows (int): Maximum number of rows to print in the
error table. The error table lists the error file, if any,
corresponding to each trial. Defaults to 20.
max_report_frequency (int): Maximum report frequency in seconds.
Defaults to 5s.
"""
def __init__(self,
overwrite,
@@ -153,23 +168,6 @@ class JupyterNotebookReporter(TuneReporterBase):
max_progress_rows=20,
max_error_rows=20,
max_report_frequency=5):
"""Initializes a new JupyterNotebookReporter.
Args:
overwrite (bool): Flag for overwriting the last reported progress.
metric_columns (dict[str, str]|list[str]): Names of metrics to
include in progress table. If this is a dict, the keys should
be metric names and the values should be the displayed names.
If this is a list, the metric name is used directly.
max_progress_rows (int): Maximum number of rows to print
in the progress table. The progress table describes the
progress of each trial. Defaults to 20.
max_error_rows (int): Maximum number of rows to print in the
error table. The error table lists the error file, if any,
corresponding to each trial. Defaults to 20.
max_report_frequency (int): Maximum report frequency in seconds.
Defaults to 5s.
"""
super(JupyterNotebookReporter,
self).__init__(metric_columns, max_progress_rows, max_error_rows,
max_report_frequency)
@@ -186,29 +184,29 @@ class JupyterNotebookReporter(TuneReporterBase):
class CLIReporter(TuneReporterBase):
"""Command-line reporter"""
"""Command-line reporter
Args:
metric_columns (dict[str, str]|list[str]): Names of metrics to
include in progress table. If this is a dict, the keys should
be metric names and the values should be the displayed names.
If this is a list, the metric name is used directly.
max_progress_rows (int): Maximum number of rows to print
in the progress table. The progress table describes the
progress of each trial. Defaults to 20.
max_error_rows (int): Maximum number of rows to print in the
error table. The error table lists the error file, if any,
corresponding to each trial. Defaults to 20.
max_report_frequency (int): Maximum report frequency in seconds.
Defaults to 5s.
"""
def __init__(self,
metric_columns=None,
max_progress_rows=20,
max_error_rows=20,
max_report_frequency=5):
"""Initializes a CLIReporter.
Args:
metric_columns (dict[str, str]|list[str]): Names of metrics to
include in progress table. If this is a dict, the keys should
be metric names and the values should be the displayed names.
If this is a list, the metric name is used directly.
max_progress_rows (int): Maximum number of rows to print
in the progress table. The progress table describes the
progress of each trial. Defaults to 20.
max_error_rows (int): Maximum number of rows to print in the
error table. The error table lists the error file, if any,
corresponding to each trial. Defaults to 20.
max_report_frequency (int): Maximum report frequency in seconds.
Defaults to 5s.
"""
super(CLIReporter, self).__init__(metric_columns, max_progress_rows,
max_error_rows, max_report_frequency)
python/ray/tune/registry.py
+6
View File
@@ -41,6 +41,9 @@ def validate_trainable(trainable_name):
def register_trainable(name, trainable):
"""Register a trainable function or class.
This enables a class or function to be accessed on every Ray process
in the cluster.
Args:
name (str): Name to register.
trainable (obj): Function or tune.Trainable class. Functions must
@@ -70,6 +73,9 @@ def register_trainable(name, trainable):
def register_env(name, env_creator):
"""Register a custom environment for use with RLlib.
This enables the environment to be accessed on every Ray process
in the cluster.
Args:
name (str): Name to register.
env_creator (obj): Function that creates an env.
python/ray/tune/resources.py
+1 -1
View File
@@ -19,7 +19,7 @@ class Resources(
])):
"""Ray resources required to schedule a trial.
Attributes:
Parameters:
cpu (float): Number of CPUs to allocate to the trial.
gpu (float): Number of GPUs to allocate to the trial.
memory (float): Memory to reserve for the trial.
python/ray/tune/schedulers/pbt.py
+21 -16
View File
@@ -149,22 +149,27 @@ class PopulationBasedTraining(FIFOScheduler):
local_dir at each exploit. Allows config schedule to be
reconstructed.
Example:
>>> pbt = PopulationBasedTraining(
>>> time_attr="training_iteration",
>>> metric="episode_reward_mean",
>>> mode="max",
>>> perturbation_interval=10, # every 10 `time_attr` units
>>> # (training_iterations in this case)
>>> hyperparam_mutations={
>>> # Perturb factor1 by scaling it by 0.8 or 1.2. Resampling
>>> # resets it to a value sampled from the lambda function.
>>> "factor_1": lambda: random.uniform(0.0, 20.0),
>>> # Perturb factor2 by changing it to an adjacent value, e.g.
>>> # 10 -> 1 or 10 -> 100. Resampling will choose at random.
>>> "factor_2": [1, 10, 100, 1000, 10000],
>>> })
>>> tune.run({...}, num_samples=8, scheduler=pbt)
.. code-block:: python
import random
from ray import tune
from ray.tune.schedulers import PopulationBasedTraining
pbt = PopulationBasedTraining(
time_attr="training_iteration",
metric="episode_reward_mean",
mode="max",
perturbation_interval=10, # every 10 `time_attr` units
# (training_iterations in this case)
hyperparam_mutations={
# Perturb factor1 by scaling it by 0.8 or 1.2. Resampling
# resets it to a value sampled from the lambda function.
"factor_1": lambda: random.uniform(0.0, 20.0),
# Perturb factor2 by changing it to an adjacent value, e.g.
# 10 -> 1 or 10 -> 100. Resampling will choose at random.
"factor_2": [1, 10, 100, 1000, 10000],
})
tune.run({...}, num_samples=8, scheduler=pbt)
"""
def __init__(self,
python/ray/tune/suggest/ax.py
+14 -7
View File
@@ -40,13 +40,20 @@ class AxSearch(SuggestionAlgorithm):
trial results in the optimization process.
Example:
>>> parameters = [
>>> {"name": "x1", "type": "range", "bounds": [0.0, 1.0]},
>>> {"name": "x2", "type": "range", "bounds": [0.0, 1.0]},
>>> ]
>>> algo = AxSearch(parameters=parameters,
>>> objective_name="hartmann6", max_concurrent=4)
.. code-block:: python
from ray import tune
from ray.tune.suggest.ax import AxSearch
parameters = [
{"name": "x1", "type": "range", "bounds": [0.0, 1.0]},
{"name": "x2", "type": "range", "bounds": [0.0, 1.0]},
]
algo = AxSearch(parameters=parameters,
objective_name="hartmann6", max_concurrent=4)
tune.run(my_func, algo=algo)
"""
def __init__(self, ax_client, max_concurrent=10, mode="max", **kwargs):
python/ray/tune/suggest/basic_variant.py
+24 -7
View File
@@ -14,18 +14,35 @@ class BasicVariantGenerator(SearchAlgorithm):
See also: `ray.tune.suggest.variant_generator`.
Example:
>>> searcher = BasicVariantGenerator()
>>> searcher.add_configurations({"experiment": { ... }})
>>> list_of_trials = searcher.next_trials()
>>> searcher.is_finished == True
Parameters:
shuffle (bool): Shuffles the generated list of configurations.
User API:
.. code-block:: python
from ray import tune
from ray.tune.suggest import BasicVariantGenerator
searcher = BasicVariantGenerator()
tune.run(my_trainable_func, algo=searcher)
Internal API:
.. code-block:: python
from ray.tune.suggest import BasicVariantGenerator
searcher = BasicVariantGenerator()
searcher.add_configurations({"experiment": { ... }})
list_of_trials = searcher.next_trials()
searcher.is_finished == True
"""
def __init__(self, shuffle=False):
"""Initializes the Variant Generator.
Arguments:
shuffle (bool): Shuffles the generated list of configurations.
"""
self._parser = make_parser()
self._trial_generator = []
python/ray/tune/suggest/bayesopt.py
+16 -8
View File
@@ -15,7 +15,7 @@ class BayesOptSearch(SuggestionAlgorithm):
"""A wrapper around BayesOpt to provide trial suggestions.
Requires BayesOpt to be installed. You can install BayesOpt with the
command: `pip install bayesian-optimization`.
command: ``pip install bayesian-optimization``.
Parameters:
space (dict): Continuous search space. Parameters will be sampled from
@@ -32,14 +32,22 @@ class BayesOptSearch(SuggestionAlgorithm):
use_early_stopped_trials (bool): Whether to use early terminated
trial results in the optimization process.
Example:
>>> space = {
>>> 'width': (0, 20),
>>> 'height': (-100, 100),
>>> }
>>> algo = BayesOptSearch(
>>> space, max_concurrent=4, metric="mean_loss", mode="min")
.. code-block:: python
from ray import tune
from ray.tune.suggest.bayesopt import BayesOptSearch
space = {
'width': (0, 20),
'height': (-100, 100),
}
algo = BayesOptSearch(
space, max_concurrent=4, metric="mean_loss", mode="min")
tune.run(my_func, algo=algo)
"""
# bayes_opt.BayesianOptimization: Optimization object
optimizer = None
def __init__(self,
space,
python/ray/tune/suggest/bohb.py
+23 -18
View File
@@ -22,7 +22,7 @@ class TuneBOHB(SuggestionAlgorithm):
Requires HpBandSter and ConfigSpace to be installed. You can install
HpBandSter and ConfigSpace with: `pip install hpbandster ConfigSpace`.
HpBandSter and ConfigSpace with: ``pip install hpbandster ConfigSpace``.
This should be used in conjunction with HyperBandForBOHB.
@@ -38,23 +38,28 @@ class TuneBOHB(SuggestionAlgorithm):
minimizing or maximizing the metric attribute.
Example:
>>> import ConfigSpace as CS
>>> config_space = CS.ConfigurationSpace()
>>> config_space.add_hyperparameter(
CS.UniformFloatHyperparameter('width', lower=0, upper=20))
>>> config_space.add_hyperparameter(
CS.UniformFloatHyperparameter('height', lower=-100, upper=100))
>>> config_space.add_hyperparameter(
CS.CategoricalHyperparameter(
name='activation', choices=['relu', 'tanh']))
>>> algo = TuneBOHB(
config_space, max_concurrent=4, metric='mean_loss', mode='min')
>>> bohb = HyperBandForBOHB(
time_attr='training_iteration',
metric='mean_loss',
mode='min',
max_t=100)
>>> run(MyTrainableClass, scheduler=bohb, search_alg=algo)
.. code-block:: python
import ConfigSpace as CS
config_space = CS.ConfigurationSpace()
config_space.add_hyperparameter(
CS.UniformFloatHyperparameter('width', lower=0, upper=20))
config_space.add_hyperparameter(
CS.UniformFloatHyperparameter('height', lower=-100, upper=100))
config_space.add_hyperparameter(
CS.CategoricalHyperparameter(
name='activation', choices=['relu', 'tanh']))
algo = TuneBOHB(
config_space, max_concurrent=4, metric='mean_loss', mode='min')
bohb = HyperBandForBOHB(
time_attr='training_iteration',
metric='mean_loss',
mode='min',
max_t=100)
run(MyTrainableClass, scheduler=bohb, search_alg=algo)
"""
python/ray/tune/suggest/dragonfly.py
+33 -27
View File
@@ -18,7 +18,7 @@ logger = logging.getLogger(__name__)
class DragonflySearch(SuggestionAlgorithm):
"""A wrapper around Dragonfly to provide trial suggestions.
Requires Dragonfly to be installed.
Requires Dragonfly to be installed via ``pip install dragonfly-opt``.
Parameters:
optimizer (dragonfly.opt.BlackboxOptimiser): Optimizer provided
@@ -40,33 +40,39 @@ class DragonflySearch(SuggestionAlgorithm):
needing to re-compute the trial. Must be the same length as
points_to_evaluate.
Example:
>>> from dragonfly.opt.gp_bandit import EuclideanGPBandit
>>> from dragonfly.exd.experiment_caller import EuclideanFunctionCaller
>>> from dragonfly import load_config
>>> domain_vars = [{
"name": "LiNO3_vol",
"type": "float",
"min": 0,
"max": 7
}, {
"name": "Li2SO4_vol",
"type": "float",
"min": 0,
"max": 7
}, {
"name": "NaClO4_vol",
"type": "float",
"min": 0,
"max": 7
}]
.. code-block:: python
>>> domain_config = load_config({"domain": domain_vars})
>>> func_caller = EuclideanFunctionCaller(None,
domain_config.domain.list_of_domains[0])
>>> optimizer = EuclideanGPBandit(func_caller, ask_tell_mode=True)
>>> algo = DragonflySearch(optimizer, max_concurrent=4,
metric="objective", mode="max")
from ray import tune
from dragonfly.opt.gp_bandit import EuclideanGPBandit
from dragonfly.exd.experiment_caller import EuclideanFunctionCaller
from dragonfly import load_config
domain_vars = [{
"name": "LiNO3_vol",
"type": "float",
"min": 0,
"max": 7
}, {
"name": "Li2SO4_vol",
"type": "float",
"min": 0,
"max": 7
}, {
"name": "NaClO4_vol",
"type": "float",
"min": 0,
"max": 7
}]
domain_config = load_config({"domain": domain_vars})
func_caller = EuclideanFunctionCaller(None,
domain_config.domain.list_of_domains[0])
optimizer = EuclideanGPBandit(func_caller, ask_tell_mode=True)
algo = DragonflySearch(optimizer, max_concurrent=4,
metric="objective", mode="max")
tune.run(my_func, algo=algo)
"""
def __init__(self,
python/ray/tune/suggest/hyperopt.py
+16 -14
View File
@@ -52,20 +52,22 @@ class HyperOptSearch(SuggestionAlgorithm):
use_early_stopped_trials (bool): Whether to use early terminated
trial results in the optimization process.
Example:
>>> space = {
>>> 'width': hp.uniform('width', 0, 20),
>>> 'height': hp.uniform('height', -100, 100),
>>> 'activation': hp.choice("activation", ["relu", "tanh"])
>>> }
>>> current_best_params = [{
>>> 'width': 10,
>>> 'height': 0,
>>> 'activation': 0, # The index of "relu"
>>> }]
>>> algo = HyperOptSearch(
>>> space, max_concurrent=4, metric="mean_loss", mode="min",
>>> points_to_evaluate=current_best_params)
.. code-block:: python
space = {
'width': hp.uniform('width', 0, 20),
'height': hp.uniform('height', -100, 100),
'activation': hp.choice("activation", ["relu", "tanh"])
}
current_best_params = [{
'width': 10,
'height': 0,
'activation': 0, # The index of "relu"
}]
algo = HyperOptSearch(
space, max_concurrent=4, metric="mean_loss", mode="min",
points_to_evaluate=current_best_params)
"""
def __init__(self,
python/ray/tune/suggest/sigopt.py
+24 -21
View File
@@ -30,27 +30,30 @@ class SigOptSearch(SuggestionAlgorithm):
minimizing or maximizing the metric attribute.
Example:
>>> space = [
>>> {
>>> 'name': 'width',
>>> 'type': 'int',
>>> 'bounds': {
>>> 'min': 0,
>>> 'max': 20
>>> },
>>> },
>>> {
>>> 'name': 'height',
>>> 'type': 'int',
>>> 'bounds': {
>>> 'min': -100,
>>> 'max': 100
>>> },
>>> },
>>> ]
>>> algo = SigOptSearch(
>>> space, name="SigOpt Example Experiment",
>>> max_concurrent=1, metric="mean_loss", mode="min")
.. code-block:: python
space = [
{
'name': 'width',
'type': 'int',
'bounds': {
'min': 0,
'max': 20
},
},
{
'name': 'height',
'type': 'int',
'bounds': {
'min': -100,
'max': 100
},
},
]
algo = SigOptSearch(
space, name="SigOpt Example Experiment",
max_concurrent=1, metric="mean_loss", mode="min")
"""
def __init__(self,
python/ray/tune/suggest/suggestion.py
+7 -6
View File
@@ -20,12 +20,13 @@ class SuggestionAlgorithm(SearchAlgorithm):
`suggest` will be passed a trial_id, which will be used in
subsequent notifications.
Example:
>>> suggester = SuggestionAlgorithm()
>>> suggester.add_configurations({ ... })
>>> new_parameters = suggester.suggest()
>>> suggester.on_trial_complete(trial_id, result)
>>> better_parameters = suggester.suggest()
.. code-block:: python
suggester = SuggestionAlgorithm()
suggester.add_configurations({ ... })
new_parameters = suggester.suggest()
suggester.on_trial_complete(trial_id, result)
better_parameters = suggester.suggest()
"""
def __init__(self, metric=None, mode="max", use_early_stopped_trials=True):
python/ray/tune/track/__init__.py
+22 -5
View File
@@ -1,6 +1,6 @@
import logging
from ray.tune.track.session import TrackSession
from ray.tune.track.session import TrackSession as _TrackSession
logger = logging.getLogger(__name__)
@@ -37,7 +37,7 @@ def init(ignore_reinit_error=True, **session_kwargs):
else:
raise ValueError(reinit_msg)
_session = TrackSession(**session_kwargs)
_session = _TrackSession(**session_kwargs)
def shutdown():
@@ -50,7 +50,25 @@ def shutdown():
def log(**kwargs):
"""Applies TrackSession.log to the trial in the current context."""
"""Logs all keyword arguments.
.. code-block:: python
import time
from ray import tune
from ray.tune import track
def run_me(config):
for iter in range(100):
time.sleep(1)
track.log(hello="world", ray="tune")
analysis = tune.run(run_me)
Args:
**kwargs: Any key value pair to be logged by Tune. Any of these
metrics can be used for early stopping or optimization.
"""
_session = get_session()
return _session.log(**kwargs)
@@ -83,6 +101,5 @@ def trial_id():
__all__ = [
"TrackSession", "session", "log", "trial_dir", "init", "shutdown",
"trial_name", "trial_id"
"session", "log", "trial_dir", "init", "shutdown", "trial_name", "trial_id"
]
python/ray/tune/trainable.py
+19 -10
View File
@@ -125,7 +125,7 @@ class Trainable:
When using Tune, Tune will convert this class into a Ray actor, which
runs on a separate process. Tune will also change the current working
directory of this process to `self.logdir`.
directory of this process to ``self.logdir``.
"""
@@ -184,18 +184,23 @@ class Trainable:
@classmethod
def default_resource_request(cls, config):
"""Returns the resource requirement for the given configuration.
"""Provides a static resource requirement for the given configuration.
This can be overriden by sub-classes to set the correct trial resource
allocation, so the user does not need to.
Example:
>>> def default_resource_request(cls, config):
>>> return Resources(
>>> cpu=0,
>>> gpu=0,
>>> extra_cpu=config["workers"],
>>> extra_gpu=int(config["use_gpu"]) * config["workers"])
.. code-block:: python
@classmethod
def default_resource_request(cls, config):
return Resources(
cpu=0,
gpu=0,
extra_cpu=config["workers"],
extra_gpu=int(config["use_gpu"]) * config["workers"])
Returns:
Resources: A Resources object consumed by Tune for queueing.
"""
return None
@@ -329,7 +334,7 @@ class Trainable:
checkpoint_dir (str): Optional dir to place the checkpoint.
Returns:
Checkpoint path or prefix that may be passed to restore().
str: Checkpoint path or prefix that may be passed to restore().
"""
checkpoint_dir = os.path.join(checkpoint_dir or self.logdir,
"checkpoint_{}".format(self._iteration))
@@ -658,6 +663,10 @@ class Trainable:
def _log_result(self, result):
"""Subclasses can optionally override this to customize logging.
The logging here is done on the worker process rather than
the driver. You may want to turn off driver logging via the
``loggers`` parameter in ``tune.run`` when overriding this function.
Args:
result (dict): Training result returned by _train().
"""
python/ray/tune/trial.py
+13
View File
@@ -131,6 +131,19 @@ class Trial:
Trials start in the PENDING state, and transition to RUNNING once started.
On error it transitions to ERROR, otherwise TERMINATED on success.
Attributes:
trainable_name (str): Name of the trainable object to be executed.
config (dict): Provided configuration dictionary with evaluated params.
trial_id (str): Unique identifier for the trial.
local_dir (str): Local_dir as passed to tune.run.
logdir (str): Directory where the trial logs are saved.
evaluated_params (dict): Evaluated parameters by search algorithm,
experiment_tag (str): Identifying trial name to show in the console.
resources (Resources): Amount of resources that this trial will use.
status (str): One of PENDING, RUNNING, PAUSED, TERMINATED, ERROR/
error_file (str): Path to the errors that this trial has raised.
"""
PENDING = "PENDING"
python/ray/tune/trial_executor.py
+4 -2
View File
@@ -8,7 +8,9 @@ logger = logging.getLogger(__name__)
class TrialExecutor:
"""Manages platform-specific details such as resource handling
"""Module for interacting with remote trainables.
Manages platform-specific details such as resource handling
and starting/stopping trials.
"""
@@ -75,7 +77,7 @@ class TrialExecutor:
Args:
trial (Trial): Trial to be started.
checkpoint(Checkpoint): A Python object or path storing the state
checkpoint (Checkpoint): A Python object or path storing the state
of trial.
"""
raise NotImplementedError("Subclasses of TrialExecutor must provide "
python/ray/tune/trial_runner.py
+23 -24
View File
@@ -70,7 +70,8 @@ class _TuneFunctionDecoder(json.JSONDecoder):
class TrialRunner:
"""A TrialRunner implements the event loop for scheduling trials on Ray.
Example:
.. code-block: python
runner = TrialRunner()
runner.add_trial(Trial(...))
runner.add_trial(Trial(...))
@@ -87,6 +88,27 @@ class TrialRunner:
could deadlock waiting for new resources to become available. Furthermore,
oversubscribing the cluster could degrade training performance, leading to
misleading benchmark results.
Args:
search_alg (SearchAlgorithm): SearchAlgorithm for generating
Trial objects.
scheduler (TrialScheduler): Defaults to FIFOScheduler.
launch_web_server (bool): Flag for starting TuneServer
local_checkpoint_dir (str): Path where
global checkpoints are stored and restored from.
remote_checkpoint_dir (str): Remote path where
global checkpoints are stored and restored from. Used
if `resume` == REMOTE.
stopper: Custom class for stopping whole experiments. See
``Stopper``.
resume (str|False): see `tune.py:run`.
sync_to_cloud (func|str): See `tune.py:run`.
server_port (int): Port number for launching TuneServer.
verbose (bool): Flag for verbosity. If False, trial results
will not be output.
checkpoint_period (int): Trial runner checkpoint periodicity in
seconds. Defaults to 10.
trial_executor (TrialExecutor): Defaults to RayTrialExecutor.
"""
CKPT_FILE_TMPL = "experiment_state-{}.json"
@@ -105,29 +127,6 @@ class TrialRunner:
verbose=True,
checkpoint_period=10,
trial_executor=None):
"""Initializes a new TrialRunner.
Args:
search_alg (SearchAlgorithm): SearchAlgorithm for generating
Trial objects.
scheduler (TrialScheduler): Defaults to FIFOScheduler.
launch_web_server (bool): Flag for starting TuneServer
local_checkpoint_dir (str): Path where
global checkpoints are stored and restored from.
remote_checkpoint_dir (str): Remote path where
global checkpoints are stored and restored from. Used
if `resume` == REMOTE.
stopper: Custom class for stopping whole experiments. See
``Stopper``.
resume (str|False): see `tune.py:run`.
sync_to_cloud (func|str): See `tune.py:run`.
server_port (int): Port number for launching TuneServer.
verbose (bool): Flag for verbosity. If False, trial results
will not be output.
checkpoint_period (int): Trial runner checkpoint periodicity in
seconds. Defaults to 10.
trial_executor (TrialExecutor): Defaults to RayTrialExecutor.
"""
self._search_alg = search_alg or BasicVariantGenerator()
self._scheduler_alg = scheduler or FIFOScheduler()
self.trial_executor = trial_executor or RayTrialExecutor()
python/ray/tune/tune.py
+10 -14
View File
@@ -98,12 +98,11 @@ def run(run_or_experiment,
trial_executor=None,
raise_on_failed_trial=True,
return_trials=False,
ray_auto_init=True,
sync_function=None):
ray_auto_init=True):
"""Executes training.
Args:
run_or_experiment (function|class|str|Experiment): If
run_or_experiment (function | class | str | :class:`Experiment`): If
function|class|str, this is the algorithm or model to train.
This may refer to the name of a built-on algorithm
(e.g. RLLib's DQN or PPO), a user-defined trainable
@@ -112,11 +111,11 @@ def run(run_or_experiment,
If Experiment, then Tune will execute training based on
Experiment.spec.
name (str): Name of experiment.
stop (dict|callable): The stopping criteria. If dict, the keys may be
any field in the return result of 'train()', whichever is
reached first. If function, it must take (trial_id, result) as
arguments and return a boolean (True if trial should be stopped,
False otherwise). This can also be a subclass of
stop (dict | callable | :class:`Stopper`): Stopping criteria. If dict,
the keys may be any field in the return result of 'train()',
whichever is reached first. If function, it must take (trial_id,
result) as arguments and return a boolean (True if trial should be
stopped, False otherwise). This can also be a subclass of
``ray.tune.Stopper``, which allows users to implement
custom experiment-wide stopping (i.e., stopping an entire Tune
run based on some time constraint).
@@ -211,14 +210,12 @@ def run(run_or_experiment,
ray_auto_init (bool): Automatically starts a local Ray cluster
if using a RayTrialExecutor (which is the default) and
if Ray is not initialized. Defaults to True.
sync_function: Deprecated. See `sync_to_cloud` and
`sync_to_driver`.
Returns:
List of Trial objects.
ExperimentAnalysis: Object for experiment analysis.
Raises:
TuneError if any trials failed and `raise_on_failed_trial` is True.
TuneError: Any trials failed and `raise_on_failed_trial` is True.
Examples:
>>> tune.run(mytrainable, scheduler=PopulationBasedTraining())
@@ -265,8 +262,7 @@ def run(run_or_experiment,
checkpoint_score_attr=checkpoint_score_attr,
export_formats=export_formats,
max_failures=max_failures,
restore=restore,
sync_function=sync_function)
restore=restore)
else:
logger.debug("Ignoring some parameters passed into tune.run.")