Version: 1.1.2

Quickstart

Ax is an open-source platform for adaptive experimentation, a technique used to efficiently tune parameters in complex systems. This guide will walk through installation, core concepts, and basic usage of Ax.

Installation

We recommend using pip to install Ax.

pip install ax-platform

Core concepts

Experiment: A process of iteratively suggesting and evaluating parameters to improve some objective.
Parameter: A variable that can be adjusted -- a collection of these form the space we are searching over during the optimization.
Objective: The value being optimized.
Trial: A set of parameters and the associated objective.
Client: An object that manages the experiment and provides methods for interacting with it.

from ax import Client, RangeParameterConfig

# 1. Initialize the Client.
client = Client()

# 2. Configure where Ax will search.
client.configure_experiment(
    name="booth_function",
    parameters=[
        RangeParameterConfig(
            name="x1",
            bounds=(-10.0, 10.0),
            parameter_type="float",
        ),
        RangeParameterConfig(
            name="x2",
            bounds=(-10.0, 10.0),
            parameter_type="float",
        ),
    ],
)

# 3. Configure a metric for Ax to target (see other Tutorials for adding constraints,
# multiple objectives, tracking metrics etc.)
client.configure_optimization(objective="-1 * booth")

# 4. Conduct the experiment with 20 trials: get each trial from Ax, evaluate the
# objective function, and log data back to Ax.
for _ in range(20):
    # Use higher value of `max_trials` to run trials in parallel.
    for trial_index, parameters in client.get_next_trials(max_trials=1).items():
        client.complete_trial(
            trial_index=trial_index,
            raw_data={
                "booth": (parameters["x1"] + 2 * parameters["x2"] - 7) ** 2
                + (2 * parameters["x1"] + parameters["x2"] - 5) ** 2
            },
        )

# 5. Obtain the best-performing configuration; the true minimum for the booth
# function is at (1, 3).
client.get_best_parameterization()

Output:
/opt/hostedtoolcache/Python/3.12.11/x64/lib/python3.12/site-packages/pyro/ops/stats.py:527: SyntaxWarning: invalid escape sequence 'g'
we have :math:ES^{*}(P,Q) ge ES^{*}(Q,Q) with equality holding if and only if :math:P=Q, i.e.
[INFO 09-09 19:32:20] ax.api.client: GenerationStrategy(name='Center+Sobol+MBM:fast', nodes=[CenterGenerationNode(next_node_name='Sobol'), GenerationNode(node_name='Sobol', generator_specs=[GeneratorSpec(generator_enum=Sobol, model_key_override=None)], transition_criteria=[MinTrials(transition_to='MBM'), MinTrials(transition_to='MBM')]), GenerationNode(node_name='MBM', generator_specs=[GeneratorSpec(generator_enum=BoTorch, model_key_override=None)], transition_criteria=[])]) chosen based on user input and problem structure.
[INFO 09-09 19:32:20] ax.api.client: Generated new trial 0 with parameters {'x1': 0.0, 'x2': 0.0} using GenerationNode CenterOfSearchSpace.
[INFO 09-09 19:32:20] ax.api.client: Trial 0 marked COMPLETED.
[INFO 09-09 19:32:20] ax.api.client: Generated new trial 1 with parameters {'x1': -2.362303, 'x2': 7.776659} using GenerationNode Sobol.
[INFO 09-09 19:32:20] ax.api.client: Trial 1 marked COMPLETED.
[INFO 09-09 19:32:20] ax.api.client: Generated new trial 2 with parameters {'x1': 3.208163, 'x2': -6.743398} using GenerationNode Sobol.
[INFO 09-09 19:32:20] ax.api.client: Trial 2 marked COMPLETED.
[INFO 09-09 19:32:20] ax.api.client: Generated new trial 3 with parameters {'x1': 6.119843, 'x2': 4.322796} using GenerationNode Sobol.
[INFO 09-09 19:32:20] ax.api.client: Trial 3 marked COMPLETED.
[INFO 09-09 19:32:20] ax.api.client: Generated new trial 4 with parameters {'x1': -9.490293, 'x2': -0.199807} using GenerationNode Sobol.
[INFO 09-09 19:32:20] ax.api.client: Trial 4 marked COMPLETED.
[INFO 09-09 19:32:21] ax.api.client: Generated new trial 5 with parameters {'x1': 0.500957, 'x2': 10.0} using GenerationNode MBM.
[INFO 09-09 19:32:21] ax.api.client: Trial 5 marked COMPLETED.
[INFO 09-09 19:32:21] ax.api.client: Generated new trial 6 with parameters {'x1': -1.910335, 'x2': -5.180131} using GenerationNode MBM.
[INFO 09-09 19:32:21] ax.api.client: Trial 6 marked COMPLETED.
[INFO 09-09 19:32:22] ax.api.client: Generated new trial 7 with parameters {'x1': 0.323665, 'x2': 3.834431} using GenerationNode MBM.
[INFO 09-09 19:32:22] ax.api.client: Trial 7 marked COMPLETED.
[INFO 09-09 19:32:22] ax.api.client: Generated new trial 8 with parameters {'x1': 2.739779, 'x2': 1.019058} using GenerationNode MBM.
[INFO 09-09 19:32:22] ax.api.client: Trial 8 marked COMPLETED.
[INFO 09-09 19:32:23] ax.api.client: Generated new trial 9 with parameters {'x1': 10.0, 'x2': -3.212439} using GenerationNode MBM.
[INFO 09-09 19:32:23] ax.api.client: Trial 9 marked COMPLETED.
[INFO 09-09 19:32:23] ax.api.client: Generated new trial 10 with parameters {'x1': -7.814815, 'x2': 10.0} using GenerationNode MBM.
[INFO 09-09 19:32:23] ax.api.client: Trial 10 marked COMPLETED.
[INFO 09-09 19:32:24] ax.api.client: Generated new trial 11 with parameters {'x1': -1.225692, 'x2': 4.202727} using GenerationNode MBM.
[INFO 09-09 19:32:24] ax.api.client: Trial 11 marked COMPLETED.
[INFO 09-09 19:32:24] ax.api.client: Generated new trial 12 with parameters {'x1': 1.098156, 'x2': 2.529426} using GenerationNode MBM.
[INFO 09-09 19:32:24] ax.api.client: Trial 12 marked COMPLETED.
[INFO 09-09 19:32:25] ax.api.client: Generated new trial 13 with parameters {'x1': -3.171463, 'x2': 5.582096} using GenerationNode MBM.
[INFO 09-09 19:32:25] ax.api.client: Trial 13 marked COMPLETED.
[INFO 09-09 19:32:25] ax.api.client: Generated new trial 14 with parameters {'x1': 10.0, 'x2': -10.0} using GenerationNode MBM.
[INFO 09-09 19:32:25] ax.api.client: Trial 14 marked COMPLETED.
[INFO 09-09 19:32:26] ax.api.client: Generated new trial 15 with parameters {'x1': 0.263474, 'x2': 3.11046} using GenerationNode MBM.
[INFO 09-09 19:32:26] ax.api.client: Trial 15 marked COMPLETED.
[INFO 09-09 19:32:27] ax.api.client: Generated new trial 16 with parameters {'x1': 1.741116, 'x2': 1.808523} using GenerationNode MBM.
[INFO 09-09 19:32:27] ax.api.client: Trial 16 marked COMPLETED.
[INFO 09-09 19:32:28] ax.api.client: Generated new trial 17 with parameters {'x1': 0.778948, 'x2': 2.539484} using GenerationNode MBM.
[INFO 09-09 19:32:28] ax.api.client: Trial 17 marked COMPLETED.
[INFO 09-09 19:32:28] ax.api.client: Generated new trial 18 with parameters {'x1': 4.328151, 'x2': -0.173315} using GenerationNode MBM.
[INFO 09-09 19:32:28] ax.api.client: Trial 18 marked COMPLETED.
/opt/hostedtoolcache/Python/3.12.11/x64/lib/python3.12/site-packages/botorch/optim/optimize.py:753: RuntimeWarning:
Optimization failed in gen_candidates_scipy with the following warning(s):
[OptimizationWarning('Optimization failed within scipy.optimize.minimize with status 2 and message ABNORMAL: .')]
Trying again with a new set of initial conditions.
[INFO 09-09 19:32:30] ax.api.client: Generated new trial 19 with parameters {'x1': 0.584263, 'x2': 3.099215} using GenerationNode MBM.
[INFO 09-09 19:32:30] ax.api.client: Trial 19 marked COMPLETED.
({'x1': 1.0981562303745913, 'x2': 2.5294261308884116},
{'booth': (np.float64(0.5583781204522893), np.float64(5.023145343672765))},
12,
'12_0')

Installation​

Core concepts​

Installation

Core concepts