<commit_before>Tune User Guide
===============

Tune Overview
-------------

Tune takes a user-defined Python function or class and evaluates it on a set of hyperparameter configurations.

Each hyperparameter configuration evaluation is called a *trial*, and multiple trials are run in parallel. Configurations are either generated by Tune or drawn from a user-specified **search algorithm**. The trials are scheduled and managed by a **trial scheduler**.

.. image:: images/tune-api.svg

More information about Tune's `search algorithms can be found here <tune-searchalg.html>`__. More information about Tune's `trial schedulers can be found here <tune-schedulers.html>`__. You can check out our `examples page <tune-examples.html>`__ for more code examples.

Tune Training API
-----------------

The Tune training API [``tune.run(Trainable)``] has two concepts:

1. The `Trainable <tune-usage.html#trainable-api>`__ API, and
2. `tune.run <tune-usage.html#launching-tune>`__.

Training can be done with either the Trainable **Class API** or **function-based API**.

Trainable API
~~~~~~~~~~~~~

The class-based API will require users to subclass ``ray.tune.Trainable``. The Trainable interface `can be found here <tune-package-ref.html#ray.tune.Trainable>`__.

Here is an example:

.. code-block:: python

    class Example(Trainable):
        def _setup(self, config):
            ...

        def _train(self):
            # run training code
            result_dict = {"accuracy": 0.5, "f1": 0.1, ...}
            return result_dict


.. autoclass::  ray.tune.Trainable
    :noindex:

Tune function-based API
~~~~~~~~~~~~~~~~~~~~~~~

User-defined functions will need to have following signature and call ``tune.track.log``, which will allow you to report metrics used for scheduling, search, or early stopping:

.. code-block:: python

    def trainable(config):
        """
        Args:
            config (dict): Parameters provided from the search algorithm
                or variant generation.
        """

        while True:
            # ...
            tune.track.log(**kwargs)


Tune will run this function on a separate thread in a Ray actor process. Note that this API is not checkpointable, since the thread will never return control back to its caller. ``tune.track`` documentation can be `found here <tune-package-ref.html#module-ray.tune.track>`__.

Both the Trainable and function-based API will have `autofilled metrics <tune-usage.html#auto-filled-results>`__ in addition to the metrics reported.

.. note::
    If you have a lambda function that you want to train, you will need to first register the function: ``tune.register_trainable("lambda_id", lambda x: ...)``. You can then use ``lambda_id`` in place of ``my_trainable``.

.. note:: See previous versions of the documentation for the ``reporter`` API.


Launching Tune
~~~~~~~~~~~~~~

Use ``tune.run`` to generate and execute your hyperparameter sweep:

.. code-block:: python

    tune.run(trainable)

    # Run a total of 10 evaluations of the Trainable. Tune runs in
    # parallel and automatically determines concurrency.
    tune.run(trainable, num_samples=10)

This function will report status on the command line until all Trials stop:

::

    == Status ==
    Using FIFO scheduling algorithm.
    Resources used: 4/8 CPUs, 0/0 GPUs
    Result logdir: ~/ray_results/my_experiment
     - train_func_0_lr=0.2,momentum=1:  RUNNING [pid=6778], 209 s, 20604 ts, 7.29 acc
     - train_func_1_lr=0.4,momentum=1:  RUNNING [pid=6780], 208 s, 20522 ts, 53.1 acc
     - train_func_2_lr=0.6,momentum=1:  TERMINATED [pid=6789], 21 s, 2190 ts, 100 acc
     - train_func_3_lr=0.2,momentum=2:  RUNNING [pid=6791], 208 s, 41004 ts, 8.37 acc
     - train_func_4_lr=0.4,momentum=2:  RUNNING [pid=6800], 209 s, 41204 ts, 70.1 acc
     - train_func_5_lr=0.6,momentum=2:  TERMINATED [pid=6809], 10 s, 2164 ts, 100 acc

All results reported by the trainable will be logged locally to a unique directory per experiment, e.g. ``~/ray_results/example-experiment`` in the above example. On a cluster, incremental results will be synced to local disk on the head node.

Trial Parallelism
~~~~~~~~~~~~~~~~~

Tune automatically runs N concurrent trials, where N is the number of CPUs (cores) on your machine. By default, Tune assumes that each trial will only require 1 CPU. You can override this with ``resources_per_trial``:

.. code-block:: python

    # If you have 4 CPUs on your machine, this will run 4 concurrent trials at a time.
    tune.run(trainable, num_samples=10)

    # If you have 4 CPUs on your machine, this will run 2 concurrent trials at a time.
    tune.run(trainable, num_samples=10, resources_per_trial={"cpu": 2})

    # If you have 4 CPUs on your machine, this will run 1 trial at a time.
    tune.run(trainable, num_samples=10, resources_per_trial={"cpu": 4})

To leverage GPUs, you can set ``gpu`` in ``resources_per_trial``.  A trial will only be executed if there are resources available. See the section on`resource allocation <tune-usage#resource-allocation-using-gpus>`_, which provides more details about GPU usage and trials that are distributed:

.. code-block:: python

    # If you have 4 CPUs on your machine and 1 GPU, this will run 1 trial at a time.
    tune.run(trainable, num_samples=10, resources_per_trial={"cpu": 2, "gpu": 1})


To attach to a Ray cluster or use ``ray.init`` manual resource overrides, simply run ``ray.init`` before ``tune.run``:

.. code-block:: python

    # Setup a local ray cluster and override resources. This will run 50 trials in parallel:
    ray.init(num_cpus=100)
    tune.run(trainable, num_samples=100, resources_per_trial={"cpu": 2})

    # Connect to an existing distributed Ray cluster
    ray.init(address=<ray_redis_address>)
    tune.run(trainable, num_samples=100, resources_per_trial={"cpu": 2, "gpu": 1})<commit_msg>[tune] Fix broken link in Tune User Guide (#6866)<commit_after>Tune User Guide
===============

Tune Overview
-------------

Tune takes a user-defined Python function or class and evaluates it on a set of hyperparameter configurations.

Each hyperparameter configuration evaluation is called a *trial*, and multiple trials are run in parallel. Configurations are either generated by Tune or drawn from a user-specified **search algorithm**. The trials are scheduled and managed by a **trial scheduler**.

.. image:: images/tune-api.svg

More information about Tune's `search algorithms can be found here <tune-searchalg.html>`__. More information about Tune's `trial schedulers can be found here <tune-schedulers.html>`__. You can check out our `examples page <tune-examples.html>`__ for more code examples.

Tune Training API
-----------------

The Tune training API [``tune.run(Trainable)``] has two concepts:

1. The `Trainable <tune-usage.html#trainable-api>`__ API, and
2. `tune.run <tune-usage.html#launching-tune>`__.

Training can be done with either the Trainable **Class API** or **function-based API**.

Trainable API
~~~~~~~~~~~~~

The class-based API will require users to subclass ``ray.tune.Trainable``. The Trainable interface `can be found here <tune-package-ref.html#ray.tune.Trainable>`__.

Here is an example:

.. code-block:: python

    class Example(Trainable):
        def _setup(self, config):
            ...

        def _train(self):
            # run training code
            result_dict = {"accuracy": 0.5, "f1": 0.1, ...}
            return result_dict


.. autoclass::  ray.tune.Trainable
    :noindex:

Tune function-based API
~~~~~~~~~~~~~~~~~~~~~~~

User-defined functions will need to have following signature and call ``tune.track.log``, which will allow you to report metrics used for scheduling, search, or early stopping:

.. code-block:: python

    def trainable(config):
        """
        Args:
            config (dict): Parameters provided from the search algorithm
                or variant generation.
        """

        while True:
            # ...
            tune.track.log(**kwargs)


Tune will run this function on a separate thread in a Ray actor process. Note that this API is not checkpointable, since the thread will never return control back to its caller. ``tune.track`` documentation can be `found here <tune-package-ref.html#module-ray.tune.track>`__.

Both the Trainable and function-based API will have `autofilled metrics <tune-usage.html#auto-filled-results>`__ in addition to the metrics reported.

.. note::
    If you have a lambda function that you want to train, you will need to first register the function: ``tune.register_trainable("lambda_id", lambda x: ...)``. You can then use ``lambda_id`` in place of ``my_trainable``.

.. note:: See previous versions of the documentation for the ``reporter`` API.


Launching Tune
~~~~~~~~~~~~~~

Use ``tune.run`` to generate and execute your hyperparameter sweep:

.. code-block:: python

    tune.run(trainable)

    # Run a total of 10 evaluations of the Trainable. Tune runs in
    # parallel and automatically determines concurrency.
    tune.run(trainable, num_samples=10)

This function will report status on the command line until all Trials stop:

::

    == Status ==
    Using FIFO scheduling algorithm.
    Resources used: 4/8 CPUs, 0/0 GPUs
    Result logdir: ~/ray_results/my_experiment
     - train_func_0_lr=0.2,momentum=1:  RUNNING [pid=6778], 209 s, 20604 ts, 7.29 acc
     - train_func_1_lr=0.4,momentum=1:  RUNNING [pid=6780], 208 s, 20522 ts, 53.1 acc
     - train_func_2_lr=0.6,momentum=1:  TERMINATED [pid=6789], 21 s, 2190 ts, 100 acc
     - train_func_3_lr=0.2,momentum=2:  RUNNING [pid=6791], 208 s, 41004 ts, 8.37 acc
     - train_func_4_lr=0.4,momentum=2:  RUNNING [pid=6800], 209 s, 41204 ts, 70.1 acc
     - train_func_5_lr=0.6,momentum=2:  TERMINATED [pid=6809], 10 s, 2164 ts, 100 acc

All results reported by the trainable will be logged locally to a unique directory per experiment, e.g. ``~/ray_results/example-experiment`` in the above example. On a cluster, incremental results will be synced to local disk on the head node.

Trial Parallelism
~~~~~~~~~~~~~~~~~

Tune automatically runs N concurrent trials, where N is the number of CPUs (cores) on your machine. By default, Tune assumes that each trial will only require 1 CPU. You can override this with ``resources_per_trial``:

.. code-block:: python

    # If you have 4 CPUs on your machine, this will run 4 concurrent trials at a time.
    tune.run(trainable, num_samples=10)

    # If you have 4 CPUs on your machine, this will run 2 concurrent trials at a time.
    tune.run(trainable, num_samples=10, resources_per_trial={"cpu": 2})

    # If you have 4 CPUs on your machine, this will run 1 trial at a time.
    tune.run(trainable, num_samples=10, resources_per_trial={"cpu": 4})

To leverage GPUs, you can set ``gpu`` in ``resources_per_trial``.  A trial will only be executed if there are resources available. See the section on `resource allocation <tune-usage.html#resource-allocation-using-gpus>`_, which provides more details about GPU usage and trials that are distributed:

.. code-block:: python

    # If you have 4 CPUs on your machine and 1 GPU, this will run 1 trial at a time.
    tune.run(trainable, num_samples=10, resources_per_trial={"cpu": 2, "gpu": 1})


To attach to a Ray cluster or use ``ray.init`` manual resource overrides, simply run ``ray.init`` before ``tune.run``:

.. code-block:: python

    # Setup a local ray cluster and override resources. This will run 50 trials in parallel:
    ray.init(num_cpus=100)
    tune.run(trainable, num_samples=100, resources_per_trial={"cpu": 2})

    # Connect to an existing distributed Ray cluster
    ray.init(address=<ray_redis_address>)
    tune.run(trainable, num_samples=100, resources_per_trial={"cpu": 2, "gpu": 1})
{'fraction_non_alphanumeric': 0.11450900441726129, 'fraction_numerical': 0.027692830445124023, 'mean_word_length': 3.6223007459756578, 'pattern_counts': {'":': 18, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1971482', 'n_tokens_mistral': 3787, 'n_tokens_neox': 3437, 'n_words': 1384}