ray.tune.search.ax.AxSearch

class ray.tune.search.ax.AxSearch(space: Optional[Union[Dict, List[Dict]]] = None, metric: Optional[str] = None, mode: Optional[str] = None, points_to_evaluate: Optional[List[Dict]] = None, parameter_constraints: Optional[List] = None, outcome_constraints: Optional[List] = None, ax_client: Optional[<MagicMock name='mock.AxClient' id='140258768379152'>] = None, **ax_kwargs)

Bases: ray.tune.search.searcher.Searcher

Uses Ax to optimize hyperparameters.

Ax is a platform for understanding, managing, deploying, and automating adaptive experiments. Ax provides an easy to use interface with BoTorch, a flexible, modern library for Bayesian optimization in PyTorch. More information can be found in https://ax.dev/.

To use this search algorithm, you must install Ax and sqlalchemy:

$ pip install ax-platform sqlalchemy

Parameters

• space – Parameters in the experiment search space. Required elements in the dictionaries are: “name” (name of this parameter, string), “type” (type of the parameter: “range”, “fixed”, or “choice”, string), “bounds” for range parameters (list of two values, lower bound first), “values” for choice parameters (list of values), and “value” for fixed parameters (single value).

• metric – Name of the metric used as objective in this experiment. This metric must be present in raw_data argument to log_data. This metric must also be present in the dict reported/returned by the Trainable. If None but a mode was passed, the ray.tune.result.DEFAULT_METRIC will be used per default.

• mode – One of {min, max}. Determines whether objective is minimizing or maximizing the metric attribute. Defaults to “max”.

• points_to_evaluate – Initial parameter suggestions to be run first. This is for when you already have some good parameters you want to run first to help the algorithm make better suggestions for future parameters. Needs to be a list of dicts containing the configurations.

• parameter_constraints – Parameter constraints, such as “x3 >= x4” or “x3 + x4 >= 2”.

• outcome_constraints – Outcome constraints of form “metric_name >= bound”, like “m1 <= 3.”

• ax_client – Optional AxClient instance. If this is set, do not pass any values to these parameters: space, metric, parameter_constraints, outcome_constraints.

• **ax_kwargs – Passed to AxClient instance. Ignored if AxClient is not None.

Tune automatically converts search spaces to Ax’s format:

from ray import tune
from ray.air import session
from ray.tune.search.ax import AxSearch

config = {
    "x1": tune.uniform(0.0, 1.0),
    "x2": tune.uniform(0.0, 1.0)
}

def easy_objective(config):
    for i in range(100):
        intermediate_result = config["x1"] + config["x2"] * i
        session.report({"score": intermediate_result})

ax_search = AxSearch()
tuner = tune.Tuner(
    easy_objective,
    tune_config=tune.TuneConfig(
        search_alg=ax_search,
        metric="score",
        mode="max",
    ),
    param_space=config,
)
tuner.fit()

If you would like to pass the search space manually, the code would look like this:

from ray import tune
from ray.air import session
from ray.tune.search.ax import AxSearch

parameters = [
    {"name": "x1", "type": "range", "bounds": [0.0, 1.0]},
    {"name": "x2", "type": "range", "bounds": [0.0, 1.0]},
]

def easy_objective(config):
    for i in range(100):
        intermediate_result = config["x1"] + config["x2"] * i
        session.report({"score": intermediate_result})

ax_search = AxSearch(space=parameters, metric="score", mode="max")
tuner = tune.Tuner(
    easy_objective,
    tune_config=tune.TuneConfig(
        search_alg=ax_search,
    ),
)
tuner.fit()

set_search_properties(metric: Optional[str], mode: Optional[str], config: Dict, **spec)

Pass search properties to searcher.

This method acts as an alternative to instantiating search algorithms with their own specific search spaces. Instead they can accept a Tune config through this method. A searcher should return True if setting the config was successful, or False if it was unsuccessful, e.g. when the search space has already been set.

Parameters

• metric – Metric to optimize

• mode – One of [“min”, “max”]. Direction to optimize.

• config – Tune config dict.

• **spec – Any kwargs for forward compatiblity. Info like Experiment.PUBLIC_KEYS is provided through here.

suggest(trial_id: str) → Optional[Dict]

Queries the algorithm to retrieve the next set of parameters.

Parameters

trial_id – Trial ID used for subsequent notifications.

Returns

Configuration for a trial, if possible.

If FINISHED is returned, Tune will be notified that no more suggestions/configurations will be provided. If None is returned, Tune will skip the querying of the searcher for this step.

Return type

dict | FINISHED | None

on_trial_complete(trial_id, result=None, error=False)

Notification for the completion of trial.

Data of form key value dictionary of metric names and values.

save(checkpoint_path: str)

Save state to path for this search algorithm.

Parameters

checkpoint_path – File where the search algorithm state is saved. This path should be used later when restoring from file.

Example:

search_alg = Searcher(...)

tuner = tune.Tuner(
    cost,
    tune_config=tune.TuneConfig(
        search_alg=search_alg,
        num_samples=5
    ),
    param_space=config
)
results = tuner.fit()

search_alg.save("./my_favorite_path.pkl")

Changed in version 0.8.7: Save is automatically called by Tuner().fit(). You can use Tuner().restore() to restore from an experiment directory such as /ray_results/trainable.

restore(checkpoint_path: str)

Restore state for this search algorithm

Parameters

checkpoint_path – File where the search algorithm state is saved. This path should be the same as the one provided to “save”.

Example:

search_alg.save("./my_favorite_path.pkl")

search_alg2 = Searcher(...)
search_alg2 = ConcurrencyLimiter(search_alg2, 1)
search_alg2.restore(checkpoint_path)
tuner = tune.Tuner(
    cost,
    tune_config=tune.TuneConfig(
        search_alg=search_alg2,
        num_samples=5
    ),
)
tuner.fit()