{"id":7026,"library":"ax-platform","title":"Adaptive Experimentation","description":"Ax is an open-source Python library for adaptive experimentation, a technique that uses machine learning to efficiently tune parameters in complex systems. It supports Bayesian optimization and bandit optimization strategies, powered by BoTorch and PyTorch. The library is actively maintained, with a typical release cadence of minor versions every few months, and the current version is 1.2.4.","status":"active","version":"1.2.4","language":"en","source_language":"en","source_url":"https://github.com/facebook/Ax","tags":["optimization","bayesian optimization","experimentation","machine learning","hyperparameter tuning","adaptive design"],"install":[{"cmd":"pip install ax-platform","lang":"bash","label":"Stable Release"},{"cmd":"pip install \"ax-platform[notebook]\"","lang":"bash","label":"With Jupyter Notebook support"},{"cmd":"pip install \"ax-platform[mysql]\"","lang":"bash","label":"With MySQL storage support"}],"dependencies":[{"reason":"Ax requires Python 3.11 or newer.","package":"python","optional":false},{"reason":"Required for data handling; Ax 1.2.3+ requires Pandas 3.0+.","package":"pandas","optional":false},{"reason":"Ax's Bayesian optimization is powered by BoTorch. Ax 1.2.3+ requires BoTorch 0.17.0+.","package":"botorch","optional":false},{"reason":"Indirect dependency via BoTorch, often manually installed for performance.","package":"pytorch","optional":false},{"reason":"Optional for SQL storage; will become a required dependency in future versions.","package":"sqlalchemy","optional":true},{"reason":"Indirect dependency via BoTorch, sometimes needed for bleeding edge installations.","package":"gpytorch","optional":true}],"imports":[{"note":"The consolidated import for the primary entry point, also `from ax.api.client import Client` is correct for the new public API.","symbol":"Client","correct":"from ax import Client"},{"note":"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.","wrong":"from ax.service.ax_client import AxClient","symbol":"AxClient","correct":"from ax.api.client import Client"},{"note":"Commonly imported alongside Client for defining search spaces.","symbol":"RangeParameterConfig","correct":"from ax import RangeParameterConfig"}],"quickstart":{"code":"from ax import Client, RangeParameterConfig\n\ndef booth_function(x1, x2):\n    return (x1 + 2 * x2 - 7)**2 + (2 * x1 + x2 - 5)**2\n\nclient = Client()\nclient.configure_experiment(\n    name=\"booth_function_experiment\",\n    parameters=[\n        RangeParameterConfig(name=\"x1\", bounds=(-10.0, 10.0), parameter_type=\"float\"),\n        RangeParameterConfig(name=\"x2\", bounds=(-10.0, 10.0), parameter_type=\"float\"),\n    ],\n    objectives={\n        \"booth\": RangeParameterConfig(name=\"booth\", bounds=(-100.0, 100.0), parameter_type=\"float\", minimize=True)\n    }\n)\n\nfor _ in range(20):\n    for trial_index, parameters in client.get_next_trials(max_trials=1).items():\n        result = booth_function(parameters[\"x1\"], parameters[\"x2\"])\n        client.complete_trial(\n            trial_index=trial_index,\n            raw_data={\"booth\": (result, 0.0)} # Tuple (mean, SEM)\n        )\n\nbest_parameters, metrics = client.get_best_parameterization()\nprint(\"Best parameters found:\", best_parameters)\nprint(\"Corresponding metrics:\", metrics)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.11 or newer. `conda create -n myenv python=3.11; conda activate myenv` or use `pyenv`.","message":"Ax 1.2.3 and later requires Python 3.11+. Older Python versions will cause installation or runtime failures.","severity":"breaking","affected_versions":">=1.2.3"},{"fix":"Ensure `pandas` and `botorch` are updated: `pip install --upgrade pandas botorch`.","message":"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.","severity":"breaking","affected_versions":">=1.2.3"},{"fix":"When defining a `GenerationStrategy` with `TransitionCriterion`, explicitly specify `transition_to` for each criterion.","message":"The `transition_to` argument is now explicitly required on `TransitionCriterion` classes in Ax 1.2.3+. Code relying on implicit transitions will fail.","severity":"breaking","affected_versions":">=1.2.3"},{"fix":"Migrate to the new public API through `from ax.api.client import Client` and manage the optimization loop manually.","message":"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.","severity":"deprecated","affected_versions":">=1.2.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0 (Ax's internal compatibility)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install ax-platform`. Ensure your virtual environment is activated.","cause":"The `ax-platform` package is not installed or not available in the current Python environment.","error":"ModuleNotFoundError: No module named 'ax-platform'"},{"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`.","cause":"This usually indicates an incompatible Python version. Ax 1.2.3+ requires Python 3.11 or newer.","error":"ERROR: Could not find a version that satisfies the requirement ax-platform"},{"fix":"Update Pandas and BoTorch: `pip install --upgrade 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+).","error":"AttributeError: 'RangeParameter' object has no attribute 'lower' (or similar attribute errors related to Pandas/BoTorch)"},{"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.","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.","error":"OptimizationWarning: Failed to initialize using continuous relaxation. Using `sample_feasible_points` for initialization."},{"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 (`\\`).","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.","error":"SyntaxWarning: invalid escape sequence 'g' (or similar 'SyntaxWarning' related to escape sequences)"}]}