Adaptive Experimentation

Common errors

• ModuleNotFoundError: No module named 'ax-platform'

  cause The `ax-platform` package is not installed or not available in the current Python environment.
  fix Install the package using pip: `pip install ax-platform`. Ensure your virtual environment is activated.

• ERROR: Could not find a version that satisfies the requirement ax-platform

  cause This usually indicates an incompatible Python version. Ax 1.2.3+ requires Python 3.11 or newer.
  fix Upgrade your Python version to 3.11+ or ensure your environment satisfies the `requires_python` metadata. You might also need to upgrade pip: `python -m pip install --upgrade pip`.

• AttributeError: 'RangeParameter' object has no attribute 'lower' (or similar attribute errors related to Pandas/BoTorch)

  cause Version mismatch with core dependencies like Pandas or BoTorch. Ax 1.2.3+ expects specific versions (Pandas 3.0+, BoTorch 0.17.0+).
  fix Update Pandas and BoTorch: `pip install --upgrade pandas botorch`.

• OptimizationWarning: Failed to initialize using continuous relaxation. Using `sample_feasible_points` for initialization.

  cause This warning from BoTorch (used by Ax) often indicates numerical issues or a challenging optimization landscape where the initial continuous optimization fails, and a fallback is used. It's often a warning, not a fatal error, but can indicate suboptimal performance.
  fix While often ignorable, check your search space definition for extreme bounds or constraints. Consider normalizing parameters. If performance is an issue, consult BoTorch documentation or Ax tutorials on advanced model configuration.

• SyntaxWarning: invalid escape sequence 'g' (or similar 'SyntaxWarning' related to escape sequences)

  cause This Python warning is often triggered by raw strings (`r'...'`) or unescaped backslashes in older code that might not be fully compliant with newer Python versions' string literal rules (e.g., Python 3.12+). It can appear in internal library code or examples.
  fix This is typically a warning from internal dependencies and might not directly impact your code's functionality, but it can be noisy. Ensure your Python version is compatible with the Ax version. If it's in your code, use raw strings (`r""`) or correctly escape backslashes (`\`).

Warnings

• breaking Ax 1.2.3 and later requires Python 3.11+. Older Python versions will cause installation or runtime failures.
  Fix: Upgrade your Python environment to 3.11 or newer. `conda create -n myenv python=3.11; conda activate myenv` or use `pyenv`.
• breaking Ax 1.2.3 and later requires Pandas 3.0+ and BoTorch 0.17.0+ due to breaking changes in their APIs. Older versions may lead to `AttributeError` or unexpected behavior.
  Fix: Ensure `pandas` and `botorch` are updated: `pip install --upgrade pandas botorch`.
• breaking The `transition_to` argument is now explicitly required on `TransitionCriterion` classes in Ax 1.2.3+. Code relying on implicit transitions will fail.
  Fix: When defining a `GenerationStrategy` with `TransitionCriterion`, explicitly specify `transition_to` for each criterion.
• deprecated The `AxClient` and the 'optimize' loop API (e.g., `ax.service.managed_loop.optimize`) are deprecated as of Ax 1.2.2. While still functional, they may be removed or changed incompatibly in future major/minor releases.
  Fix: Migrate to the new public API through `from ax.api.client import Client` and manage the optimization loop manually.
• gotcha SQLAlchemy is not a direct dependency in current Ax versions but is recommended for SQL storage. If installed, `SQLAlchemy>=2.0` can cause compatibility issues with Ax's internal storage components.
  Fix: If using SQL storage, ensure `SQLAlchemy` is installed but keep its version below 2.0 (e.g., `pip install 'SQLAlchemy<2.0'`) until Ax explicitly supports 2.0. Ax 1.2.2 notes that SQLAlchemy will become a required dependency in a future release.

Install

• pip install ax-platform Stable Release
• pip install "ax-platform[notebook]" With Jupyter Notebook support
• pip install "ax-platform[mysql]" With MySQL storage support

Imports

• Client

  from ax import Client

  The consolidated import for the primary entry point, also `from ax.api.client import Client` is correct for the new public API.
• AxClient
  wrong:

  from ax.service.ax_client import AxClient

  correct:

  from ax.api.client import Client

  The `AxClient` from `ax.service.ax_client` is part of the deprecated 'Service API'; users are encouraged to use the `ax.api` entry point, which provides the `Client` class.
• RangeParameterConfig

  from ax import RangeParameterConfig

  Commonly imported alongside Client for defining search spaces.

Quickstart

This quickstart initializes an Ax client, configures an experiment to minimize the Booth function, runs 20 trials, and then retrieves the best-found parameters. It demonstrates the core loop of defining a search space, getting new trials, evaluating them, and logging results back to Ax.

from ax import Client, RangeParameterConfig

def booth_function(x1, x2):
    return (x1 + 2 * x2 - 7)**2 + (2 * x1 + x2 - 5)**2

client = Client()
client.configure_experiment(
    name="booth_function_experiment",
    parameters=[
        RangeParameterConfig(name="x1", bounds=(-10.0, 10.0), parameter_type="float"),
        RangeParameterConfig(name="x2", bounds=(-10.0, 10.0), parameter_type="float"),
    ],
    objectives={
        "booth": RangeParameterConfig(name="booth", bounds=(-100.0, 100.0), parameter_type="float", minimize=True)
    }
)

for _ in range(20):
    for trial_index, parameters in client.get_next_trials(max_trials=1).items():
        result = booth_function(parameters["x1"], parameters["x2"])
        client.complete_trial(
            trial_index=trial_index,
            raw_data={"booth": (result, 0.0)} # Tuple (mean, SEM)
        )

best_parameters, metrics = client.get_best_parameterization()
print("Best parameters found:", best_parameters)
print("Corresponding metrics:", metrics)