diff --git a/doc/Makefile b/doc/Makefile index 77299209a..e405ab8ee 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build diff --git a/doc/source/_static/css/custom.css b/doc/source/_static/css/custom.css new file mode 100644 index 000000000..f2b64aaa7 --- /dev/null +++ b/doc/source/_static/css/custom.css @@ -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 +} diff --git a/doc/source/conf.py b/doc/source/conf.py index 24297e98b..3ac5fe478 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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) diff --git a/doc/source/development.rst b/doc/source/development.rst index 259f7dc4e..0f9eca232 100644 --- a/doc/source/development.rst +++ b/doc/source/development.rst @@ -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 `_ 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 `_ with +is opened using `Travis-CI `_ 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 `_ to +please visit `this link `_ 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 `_ 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 diff --git a/doc/source/tune-contrib.rst b/doc/source/tune-contrib.rst index 4774791e3..33fbd3b0c 100644 --- a/doc/source/tune-contrib.rst +++ b/doc/source/tune-contrib.rst @@ -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 `__), you can develop Tune locally without needing to compile Ray. - -First, you will need your own `fork `__ to work on the code. Press the Fork button on the `ray project page `__. -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 `__ and have the latest `wheel `__ installed.) - -Then, run `[path to ray directory]/python/ray/setup-dev.py` `(also here on Github) `__ 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" `__ and `"help wanted" `__ 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 `__. -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 `__. 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 `__ 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" `__ and `"help wanted" `__ 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 `__. +Here, you can track and identify how issues are organized. + + Becoming a Reviewer ------------------- diff --git a/doc/source/tune-package-ref.rst b/doc/source/tune-package-ref.rst index c83451720..8c867b0a0 100644 --- a/doc/source/tune-package-ref.rst +++ b/doc/source/tune-package-ref.rst @@ -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 diff --git a/python/ray/tune/analysis/experiment_analysis.py b/python/ray/tune/analysis/experiment_analysis.py index 854ec5307..917580676 100644 --- a/python/ray/tune/analysis/experiment_analysis.py +++ b/python/ray/tune/analysis/experiment_analysis.py @@ -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 diff --git a/python/ray/tune/experiment.py b/python/ray/tune/experiment.py index 1e91c364a..dc2b940ed 100644 --- a/python/ray/tune/experiment.py +++ b/python/ray/tune/experiment.py @@ -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) diff --git a/python/ray/tune/logger.py b/python/ray/tune/logger.py index 65b51c1a2..f46520bf0 100644 --- a/python/ray/tune/logger.py +++ b/python/ray/tune/logger.py @@ -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 diff --git a/python/ray/tune/progress_reporter.py b/python/ray/tune/progress_reporter.py index e57eb5804..3584fa5a9 100644 --- a/python/ray/tune/progress_reporter.py +++ b/python/ray/tune/progress_reporter.py @@ -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) diff --git a/python/ray/tune/registry.py b/python/ray/tune/registry.py index 11b8ac4c3..9cda439cb 100644 --- a/python/ray/tune/registry.py +++ b/python/ray/tune/registry.py @@ -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. diff --git a/python/ray/tune/resources.py b/python/ray/tune/resources.py index 8f86ad707..991832840 100644 --- a/python/ray/tune/resources.py +++ b/python/ray/tune/resources.py @@ -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. diff --git a/python/ray/tune/schedulers/pbt.py b/python/ray/tune/schedulers/pbt.py index d868b8289..29304483e 100644 --- a/python/ray/tune/schedulers/pbt.py +++ b/python/ray/tune/schedulers/pbt.py @@ -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, diff --git a/python/ray/tune/suggest/ax.py b/python/ray/tune/suggest/ax.py index d1fcb1d48..b6d7a9545 100644 --- a/python/ray/tune/suggest/ax.py +++ b/python/ray/tune/suggest/ax.py @@ -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): diff --git a/python/ray/tune/suggest/basic_variant.py b/python/ray/tune/suggest/basic_variant.py index 3216c9b9e..86872690b 100644 --- a/python/ray/tune/suggest/basic_variant.py +++ b/python/ray/tune/suggest/basic_variant.py @@ -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 = [] diff --git a/python/ray/tune/suggest/bayesopt.py b/python/ray/tune/suggest/bayesopt.py index 50737086d..1f0badf71 100644 --- a/python/ray/tune/suggest/bayesopt.py +++ b/python/ray/tune/suggest/bayesopt.py @@ -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, diff --git a/python/ray/tune/suggest/bohb.py b/python/ray/tune/suggest/bohb.py index 32b37f9cc..59f89daee 100644 --- a/python/ray/tune/suggest/bohb.py +++ b/python/ray/tune/suggest/bohb.py @@ -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) """ diff --git a/python/ray/tune/suggest/dragonfly.py b/python/ray/tune/suggest/dragonfly.py index eeb6d2d8f..50eb0047a 100644 --- a/python/ray/tune/suggest/dragonfly.py +++ b/python/ray/tune/suggest/dragonfly.py @@ -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, diff --git a/python/ray/tune/suggest/hyperopt.py b/python/ray/tune/suggest/hyperopt.py index 7dc434823..24993bb79 100644 --- a/python/ray/tune/suggest/hyperopt.py +++ b/python/ray/tune/suggest/hyperopt.py @@ -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, diff --git a/python/ray/tune/suggest/sigopt.py b/python/ray/tune/suggest/sigopt.py index 1aa9baf5f..aa7af6b82 100644 --- a/python/ray/tune/suggest/sigopt.py +++ b/python/ray/tune/suggest/sigopt.py @@ -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, diff --git a/python/ray/tune/suggest/suggestion.py b/python/ray/tune/suggest/suggestion.py index f4fc11b88..df62c0740 100644 --- a/python/ray/tune/suggest/suggestion.py +++ b/python/ray/tune/suggest/suggestion.py @@ -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): diff --git a/python/ray/tune/track/__init__.py b/python/ray/tune/track/__init__.py index 98273978e..2fc70800a 100644 --- a/python/ray/tune/track/__init__.py +++ b/python/ray/tune/track/__init__.py @@ -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" ] diff --git a/python/ray/tune/trainable.py b/python/ray/tune/trainable.py index a3fe79c2b..ebf5852b4 100644 --- a/python/ray/tune/trainable.py +++ b/python/ray/tune/trainable.py @@ -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(). """ diff --git a/python/ray/tune/trial.py b/python/ray/tune/trial.py index 6bbc7e0ed..d74126539 100644 --- a/python/ray/tune/trial.py +++ b/python/ray/tune/trial.py @@ -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" diff --git a/python/ray/tune/trial_executor.py b/python/ray/tune/trial_executor.py index 6cff1ec24..37e656567 100644 --- a/python/ray/tune/trial_executor.py +++ b/python/ray/tune/trial_executor.py @@ -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 " diff --git a/python/ray/tune/trial_runner.py b/python/ray/tune/trial_runner.py index 81b25147b..78403965a 100644 --- a/python/ray/tune/trial_runner.py +++ b/python/ray/tune/trial_runner.py @@ -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() diff --git a/python/ray/tune/tune.py b/python/ray/tune/tune.py index 5919c6557..6b14a60db 100644 --- a/python/ray/tune/tune.py +++ b/python/ray/tune/tune.py @@ -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.")