Ax Service API with RayTune on PyTorch CNN¶

Ax integrates easily with different scheduling frameworks and distributed training frameworks. In this example, Ax-driven optimization is executed in a distributed fashion using RayTune.

RayTune is a scalable framework for hyperparameter tuning that provides many state-of-the-art hyperparameter tuning algorithms and seamlessly scales from laptop to distributed cluster with fault tolerance. RayTune leverages Ray's Actor API to provide asynchronous parallel and distributed execution.

Ray 'Actors' are a simple and clean abstraction for replicating your Python classes across multiple workers and nodes. Each hyperparameter evaluation is asynchronously executed on a separate Ray actor and reports intermediate training progress back to RayTune. Upon reporting, RayTune then uses this information to performs actions such as early termination, re-prioritization, or checkpointing.

In [1]:

import logging

from ray import tune
from ray.tune import report
from ray.tune.suggest.ax import AxSearch

logger = logging.getLogger(tune.__name__)
logger.setLevel(
    level=logging.CRITICAL
)  # Reduce the number of Ray warnings that are not relevant here.

/tmp/ipykernel_3042/1865771151.py:5: DeprecationWarning: The module `ray.tune.suggest` has been moved to `ray.tune.search` and the old location will be deprecated soon. Please adjust your imports to point to the new location. Example: Do a global search and replace `ray.tune.suggest` with `ray.tune.search`.
  from ray.tune.suggest.ax import AxSearch
/tmp/ipykernel_3042/1865771151.py:5: DeprecationWarning: The module `ray.tune.suggest.ax` has been moved to `ray.tune.search.ax` and the old location will be deprecated soon. Please adjust your imports to point to the new location. Example: Do a global search and replace `ray.tune.suggest.ax` with `ray.tune.search.ax`.
  from ray.tune.suggest.ax import AxSearch

In [2]:

import numpy as np
import torch
from ax.plot.contour import plot_contour
from ax.plot.trace import optimization_trace_single_method
from ax.service.ax_client import AxClient
from ax.utils.notebook.plotting import init_notebook_plotting, render
from ax.utils.tutorials.cnn_utils import CNN, evaluate, load_mnist, train

init_notebook_plotting()

[INFO 11-10 20:39:28] ax.utils.notebook.plotting: Injecting Plotly library into cell. Do not overwrite or delete cell.

1. Initialize client¶

We specify enforce_sequential_optimization as False, because Ray runs many trials in parallel. With the sequential optimization enforcement, AxClient would expect the first few trials to be completed with data before generating more trials.

When high parallelism is not required, it is best to enforce sequential optimization, as it allows for achieving optimal results in fewer (but sequential) trials. In cases where parallelism is important, such as with distributed training using Ray, we choose to forego minimizing resource utilization and run more trials in parallel.

In [3]:

ax = AxClient(enforce_sequential_optimization=False)

[INFO 11-10 20:39:28] ax.service.ax_client: Starting optimization with verbose logging. To disable logging, set the `verbose_logging` argument to `False`. Note that float values in the logs are rounded to 6 decimal points.

2. Set up experiment¶

Here we set up the search space and specify the objective; refer to the Ax API tutorials for more detail.

In [4]:

MINIMIZE = False  # Whether we should be minimizing or maximizing the objective

In [5]:

ax.create_experiment(
    name="mnist_experiment",
    parameters=[
        {"name": "lr", "type": "range", "bounds": [1e-6, 0.4], "log_scale": True},
        {"name": "momentum", "type": "range", "bounds": [0.0, 1.0]},
    ],
    objective_name="mean_accuracy",
    minimize=MINIMIZE,
)

[INFO 11-10 20:39:28] ax.service.utils.instantiation: Inferred value type of ParameterType.FLOAT for parameter lr. If that is not the expected value type, you can explicity specify 'value_type' ('int', 'float', 'bool' or 'str') in parameter dict.
[INFO 11-10 20:39:28] ax.service.utils.instantiation: Inferred value type of ParameterType.FLOAT for parameter momentum. If that is not the expected value type, you can explicity specify 'value_type' ('int', 'float', 'bool' or 'str') in parameter dict.
[INFO 11-10 20:39:28] ax.service.utils.instantiation: Created search space: SearchSpace(parameters=[RangeParameter(name='lr', parameter_type=FLOAT, range=[1e-06, 0.4], log_scale=True), RangeParameter(name='momentum', parameter_type=FLOAT, range=[0.0, 1.0])], parameter_constraints=[]).
[INFO 11-10 20:39:28] ax.modelbridge.dispatch_utils: Using Bayesian optimization since there are more ordered parameters than there are categories for the unordered categorical parameters.
[INFO 11-10 20:39:28] ax.modelbridge.dispatch_utils: Using Bayesian Optimization generation strategy: GenerationStrategy(name='Sobol+GPEI', steps=[Sobol for 5 trials, GPEI for subsequent trials]). Iterations after 5 will take longer to generate due to  model-fitting.

In [6]:

ax.experiment.optimization_config.objective.minimize

Out[6]:

False

In [7]:

load_mnist(data_path="~/.data")  # Pre-load the dataset before the initial evaluations are executed.

Downloading http://yann.lecun.com/exdb/mnist/train-images-idx3-ubyte.gz
Downloading http://yann.lecun.com/exdb/mnist/train-images-idx3-ubyte.gz to /home/runner/.data/MNIST/raw/train-images-idx3-ubyte.gz

  0%|          | 0/9912422 [00:00<?, ?it/s]

Extracting /home/runner/.data/MNIST/raw/train-images-idx3-ubyte.gz to /home/runner/.data/MNIST/raw

Downloading http://yann.lecun.com/exdb/mnist/train-labels-idx1-ubyte.gz
Downloading http://yann.lecun.com/exdb/mnist/train-labels-idx1-ubyte.gz to /home/runner/.data/MNIST/raw/train-labels-idx1-ubyte.gz

  0%|          | 0/28881 [00:00<?, ?it/s]

Extracting /home/runner/.data/MNIST/raw/train-labels-idx1-ubyte.gz to /home/runner/.data/MNIST/raw

Downloading http://yann.lecun.com/exdb/mnist/t10k-images-idx3-ubyte.gz
Downloading http://yann.lecun.com/exdb/mnist/t10k-images-idx3-ubyte.gz to /home/runner/.data/MNIST/raw/t10k-images-idx3-ubyte.gz

  0%|          | 0/1648877 [00:00<?, ?it/s]

Extracting /home/runner/.data/MNIST/raw/t10k-images-idx3-ubyte.gz to /home/runner/.data/MNIST/raw

Downloading http://yann.lecun.com/exdb/mnist/t10k-labels-idx1-ubyte.gz
Downloading http://yann.lecun.com/exdb/mnist/t10k-labels-idx1-ubyte.gz to /home/runner/.data/MNIST/raw/t10k-labels-idx1-ubyte.gz

  0%|          | 0/4542 [00:00<?, ?it/s]

Extracting /home/runner/.data/MNIST/raw/t10k-labels-idx1-ubyte.gz to /home/runner/.data/MNIST/raw

Out[7]:

(<torch.utils.data.dataloader.DataLoader at 0x7f134c2efdf0>,
 <torch.utils.data.dataloader.DataLoader at 0x7f12986389d0>,
 <torch.utils.data.dataloader.DataLoader at 0x7f1298638a30>)

3. Define how to evaluate trials¶

Since we use the Ax Service API here, we evaluate the parameterizations that Ax suggests, using RayTune. The evaluation function follows its usual pattern, taking in a parameterization and outputting an objective value. For detail on evaluation functions, see Trial Evaluation.

In [8]:

def train_evaluate(parameterization):
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    train_loader, valid_loader, test_loader = load_mnist(data_path="~/.data")
    net = train(
        net=CNN(),
        train_loader=train_loader,
        parameters=parameterization,
        dtype=torch.float,
        device=device,
    )
    report(
        mean_accuracy=evaluate(
            net=net,
            data_loader=valid_loader,
            dtype=torch.float,
            device=device,
        )
    )

4. Run optimization¶

Execute the Ax optimization and trial evaluation in RayTune using AxSearch algorithm:

In [9]:

# Set up AxSearcher in RayTune
algo = AxSearch(ax_client=ax)
# Wrap AxSearcher in a concurrently limiter, to ensure that Bayesian optimization receives the
# data for completed trials before creating more trials
algo = tune.suggest.ConcurrencyLimiter(algo, max_concurrent=3)
tune.run(
    train_evaluate,
    num_samples=30,
    search_alg=algo,
    verbose=0,  # Set this level to 1 to see status updates and to 2 to also see trial results.
    # To use GPU, specify: resources_per_trial={"gpu": 1}.
)

/home/runner/work/Ax/Ax/ax/core/observation.py:274: FutureWarning:

In a future version of pandas, a length 1 tuple will be returned when iterating over a groupby with a grouper equal to a list of length 1. Don't supply a list with a single grouper to avoid this warning.

[INFO 11-10 20:39:33] ax.service.ax_client: Generated new trial 0 with parameters {'lr': 0.012037, 'momentum': 0.830258}.
/home/runner/work/Ax/Ax/ax/core/observation.py:274: FutureWarning:

In a future version of pandas, a length 1 tuple will be returned when iterating over a groupby with a grouper equal to a list of length 1. Don't supply a list with a single grouper to avoid this warning.

[INFO 11-10 20:39:34] ax.service.ax_client: Generated new trial 1 with parameters {'lr': 3e-06, 'momentum': 0.818551}.
/home/runner/work/Ax/Ax/ax/core/observation.py:274: FutureWarning:

In a future version of pandas, a length 1 tuple will be returned when iterating over a groupby with a grouper equal to a list of length 1. Don't supply a list with a single grouper to avoid this warning.

[INFO 11-10 20:39:34] ax.service.ax_client: Generated new trial 2 with parameters {'lr': 8e-06, 'momentum': 0.39277}.
[INFO 11-10 20:39:50] ax.service.ax_client: Completed trial 0 with data: {'mean_accuracy': (0.099167, None)}.
[INFO 11-10 20:39:50] ax.service.ax_client: Generated new trial 3 with parameters {'lr': 3e-06, 'momentum': 0.617017}.
[INFO 11-10 20:39:51] ax.service.ax_client: Completed trial 1 with data: {'mean_accuracy': (0.558333, None)}.
[INFO 11-10 20:39:51] ax.service.ax_client: Generated new trial 4 with parameters {'lr': 0.023202, 'momentum': 0.363649}.
[INFO 11-10 20:40:01] ax.service.ax_client: Completed trial 2 with data: {'mean_accuracy': (0.658333, None)}.
[INFO 11-10 20:40:01] ax.service.ax_client: Generated new trial 5 with parameters {'lr': 1e-06, 'momentum': 0.046931}.
[INFO 11-10 20:40:05] ax.service.ax_client: Completed trial 3 with data: {'mean_accuracy': (0.5395, None)}.
[INFO 11-10 20:40:05] ax.service.ax_client: Generated new trial 6 with parameters {'lr': 6.8e-05, 'momentum': 0.037269}.
[INFO 11-10 20:40:15] ax.service.ax_client: Completed trial 4 with data: {'mean_accuracy': (0.12, None)}.
[INFO 11-10 20:40:16] ax.service.ax_client: Generated new trial 7 with parameters {'lr': 2.9e-05, 'momentum': 0.652273}.
[INFO 11-10 20:40:18] ax.service.ax_client: Completed trial 5 with data: {'mean_accuracy': (0.106333, None)}.
[INFO 11-10 20:40:19] ax.service.ax_client: Generated new trial 8 with parameters {'lr': 1.1e-05, 'momentum': 0.642281}.
[INFO 11-10 20:40:29] ax.service.ax_client: Completed trial 6 with data: {'mean_accuracy': (0.870667, None)}.
[INFO 11-10 20:40:31] ax.service.ax_client: Generated new trial 9 with parameters {'lr': 0.000101, 'momentum': 0.313384}.
[INFO 11-10 20:40:33] ax.service.ax_client: Completed trial 7 with data: {'mean_accuracy': (0.8855, None)}.
[INFO 11-10 20:40:35] ax.service.ax_client: Generated new trial 10 with parameters {'lr': 6.2e-05, 'momentum': 1.0}.
[INFO 11-10 20:40:45] ax.service.ax_client: Completed trial 8 with data: {'mean_accuracy': (0.745333, None)}.
[INFO 11-10 20:40:46] ax.service.ax_client: Generated new trial 11 with parameters {'lr': 5.6e-05, 'momentum': 0.427673}.
[INFO 11-10 20:40:49] ax.service.ax_client: Completed trial 9 with data: {'mean_accuracy': (0.904167, None)}.
[INFO 11-10 20:40:52] ax.service.ax_client: Generated new trial 12 with parameters {'lr': 8.7e-05, 'momentum': 0.675164}.
[INFO 11-10 20:40:58] ax.service.ax_client: Completed trial 10 with data: {'mean_accuracy': (0.893167, None)}.
[INFO 11-10 20:41:00] ax.service.ax_client: Generated new trial 13 with parameters {'lr': 0.000272, 'momentum': 0.0}.
[INFO 11-10 20:41:03] ax.service.ax_client: Completed trial 11 with data: {'mean_accuracy': (0.885667, None)}.
[INFO 11-10 20:41:06] ax.service.ax_client: Generated new trial 14 with parameters {'lr': 5.1e-05, 'momentum': 0.803994}.
[INFO 11-10 20:41:11] ax.service.ax_client: Completed trial 12 with data: {'mean_accuracy': (0.927667, None)}.
[INFO 11-10 20:41:13] ax.service.ax_client: Generated new trial 15 with parameters {'lr': 0.000151, 'momentum': 0.837491}.
[INFO 11-10 20:41:19] ax.service.ax_client: Completed trial 13 with data: {'mean_accuracy': (0.916167, None)}.
[INFO 11-10 20:41:21] ax.service.ax_client: Generated new trial 16 with parameters {'lr': 0.00018, 'momentum': 0.100658}.
[INFO 11-10 20:41:27] ax.service.ax_client: Completed trial 14 with data: {'mean_accuracy': (0.9195, None)}.
[INFO 11-10 20:41:29] ax.service.ax_client: Generated new trial 17 with parameters {'lr': 0.000169, 'momentum': 0.0}.
[INFO 11-10 20:41:35] ax.service.ax_client: Completed trial 15 with data: {'mean_accuracy': (0.946667, None)}.
[INFO 11-10 20:41:36] ax.service.ax_client: Generated new trial 18 with parameters {'lr': 0.000288, 'momentum': 0.610035}.
[INFO 11-10 20:41:43] ax.service.ax_client: Completed trial 16 with data: {'mean_accuracy': (0.897833, None)}.
[INFO 11-10 20:41:45] ax.service.ax_client: Generated new trial 19 with parameters {'lr': 0.000107, 'momentum': 0.806491}.
[INFO 11-10 20:41:51] ax.service.ax_client: Completed trial 17 with data: {'mean_accuracy': (0.9025, None)}.
[INFO 11-10 20:41:53] ax.service.ax_client: Generated new trial 20 with parameters {'lr': 0.000218, 'momentum': 1.0}.
[INFO 11-10 20:41:58] ax.service.ax_client: Completed trial 18 with data: {'mean_accuracy': (0.941667, None)}.
[INFO 11-10 20:42:00] ax.service.ax_client: Generated new trial 21 with parameters {'lr': 0.000191, 'momentum': 0.709935}.
[INFO 11-10 20:42:07] ax.service.ax_client: Completed trial 19 with data: {'mean_accuracy': (0.9325, None)}.
[INFO 11-10 20:42:09] ax.service.ax_client: Generated new trial 22 with parameters {'lr': 0.000291, 'momentum': 0.856718}.
[INFO 11-10 20:42:13] ax.service.ax_client: Completed trial 20 with data: {'mean_accuracy': (0.534667, None)}.
[INFO 11-10 20:42:14] ax.service.ax_client: Generated new trial 23 with parameters {'lr': 0.00024, 'momentum': 0.437708}.
[INFO 11-10 20:42:22] ax.service.ax_client: Completed trial 21 with data: {'mean_accuracy': (0.941, None)}.
[INFO 11-10 20:42:24] ax.service.ax_client: Generated new trial 24 with parameters {'lr': 0.000151, 'momentum': 0.590572}.
[INFO 11-10 20:42:28] ax.service.ax_client: Completed trial 22 with data: {'mean_accuracy': (0.955833, None)}.
[INFO 11-10 20:42:30] ax.service.ax_client: Generated new trial 25 with parameters {'lr': 0.00087, 'momentum': 0.0}.
[INFO 11-10 20:42:36] ax.service.ax_client: Completed trial 23 with data: {'mean_accuracy': (0.9435, None)}.
[INFO 11-10 20:42:38] ax.service.ax_client: Generated new trial 26 with parameters {'lr': 0.000372, 'momentum': 0.284759}.
[INFO 11-10 20:42:42] ax.service.ax_client: Completed trial 24 with data: {'mean_accuracy': (0.924667, None)}.
[INFO 11-10 20:42:43] ax.service.ax_client: Generated new trial 27 with parameters {'lr': 1.9e-05, 'momentum': 1.0}.
[INFO 11-10 20:42:52] ax.service.ax_client: Completed trial 25 with data: {'mean_accuracy': (0.948833, None)}.
[INFO 11-10 20:42:54] ax.service.ax_client: Generated new trial 28 with parameters {'lr': 0.000747, 'momentum': 0.277622}.
[INFO 11-10 20:42:55] ax.service.ax_client: Completed trial 26 with data: {'mean_accuracy': (0.935167, None)}.
[INFO 11-10 20:42:57] ax.service.ax_client: Generated new trial 29 with parameters {'lr': 0.000428, 'momentum': 0.133523}.
[INFO 11-10 20:43:06] ax.service.ax_client: Completed trial 27 with data: {'mean_accuracy': (0.866, None)}.
[INFO 11-10 20:43:10] ax.service.ax_client: Completed trial 28 with data: {'mean_accuracy': (0.950667, None)}.
[INFO 11-10 20:43:18] ax.service.ax_client: Completed trial 29 with data: {'mean_accuracy': (0.9385, None)}.

Out[9]:

<ray.tune.analysis.experiment_analysis.ExperimentAnalysis at 0x7f12983579d0>

5. Retrieve the optimization results¶

In [10]:

best_parameters, values = ax.get_best_parameters()
best_parameters

Out[10]:

{'lr': 0.00019082842477609628, 'momentum': 0.7099346289794435}

In [11]:

means, covariances = values
means

Out[11]:

{'mean_accuracy': 0.950320994659047}

6. Plot the response surface and optimization trace¶

In [12]:

render(
    plot_contour(
        model=ax.generation_strategy.model,
        param_x="lr",
        param_y="momentum",
        metric_name="mean_accuracy",
    )
)

In [13]:

# `plot_single_method` expects a 2-d array of means, because it expects to average means from multiple
# optimization runs, so we wrap out best objectives array in another array.
best_objectives = np.array(
    [[trial.objective_mean * 100 for trial in ax.experiment.trials.values()]]
)
best_objective_plot = optimization_trace_single_method(
    y=np.maximum.accumulate(best_objectives, axis=1),
    title="Model performance vs. # of iterations",
    ylabel="Accuracy",
)
render(best_objective_plot)

Download Tutorial Jupyter Notebook

Download Tutorial Source Code

Total runtime of script: 4 minutes, 3.07 seconds.