Deprecate no_bayesian_optimization argument in favor of `force_rand…

…om_search` (facebook#2693)

Summary:
Pull Request resolved: facebook#2693

This deprecates the `no_bayesian_optimization` argument in favor of `force_random_search`. It is a "soft" deprecation in which we continue to provide support for the `no_bayesian_optimization` argument, but we turn it into an *optional* one and raise a deprecation warning when it is specified explicitly by the user.

If this soft deprecation does not start any fires in the coming few weeks, we will move forward with a "hard" deprecation in follow-up task T199632397.

- In the `GenerationStrategyConfig` dataclass we turned `no_bayesian_optimization` into an [init-only variable](https://docs.python.org/3/library/dataclasses.html#init-only-variables) (so it no longer become a "field").
- Everywhere that it appears as an argument, `no_bayesian_optimization` is now an *optional* argument with a default value of `None`. Whenever it is not `None`, we raise a deprecation warning and, whenever its value conflicts with `force_random_search` (non-optional, default `False`), we raise a `ValueError`.

Differential Revision: D61601511

ax/modelbridge/dispatch_utils.py

@@ -23,6 +23,7 @@
 from ax.models.torch.botorch_modular.model import BoTorchModel as ModularBoTorchModel
 from ax.models.types import TConfig
 from ax.models.winsorization_config import WinsorizationConfig
+from ax.utils.common.deprecation import _validate_force_random_search
 from ax.utils.common.logger import get_logger
 from ax.utils.common.typeutils import not_none
 
@@ -295,7 +296,8 @@ def choose_generation_strategy(
  Union[WinsorizationConfig, dict[str, WinsorizationConfig]]
  ] = None,
  derelativize_with_raw_status_quo: bool = False,
- no_bayesian_optimization: bool = False,
+ no_bayesian_optimization: Optional[bool] = None,
+ force_random_search: bool = False,
  num_trials: Optional[int] = None,
  num_initialization_trials: Optional[int] = None,
  num_completed_initialization_trials: int = 0,
@@ -347,8 +349,9 @@ def choose_generation_strategy(
  Winsorization when relative constraints are present. Note: automatic
  Winsorization will fail if this is set to `False` (or unset) and there
  are relative constraints present.
- no_bayesian_optimization: If True, Bayesian optimization generation
- strategy will not be suggested and quasi-random strategy will be used.
+ no_bayesian_optimization: Deprecated. Use `force_random_search`.
+ force_random_search: If True, quasi-random generation strategy will be used
+ rather than Bayesian optimization.
  num_trials: Total number of trials in the optimization, if
  known in advance.
  num_initialization_trials: Specific number of initialization trials, if wanted.
@@ -441,7 +444,10 @@ def choose_generation_strategy(
  sobol_parallelism = None # No restriction on Sobol phase
  bo_parallelism = DEFAULT_BAYESIAN_PARALLELISM
 
- if not no_bayesian_optimization and suggested_model is not None:
+ # TODO[T199632397] Remove
+ _validate_force_random_search(no_bayesian_optimization, force_random_search)
+
+ if not force_random_search and suggested_model is not None:
  if not enforce_sequential_optimization and (
  max_parallelism_override or max_parallelism_cap
  ):
@@ -546,7 +552,7 @@ def choose_generation_strategy(
  f" {num_remaining_initialization_trials} will take longer to generate due"
  " to model-fitting."
  )
- else: # `no_bayesian_optimization` is True or we could not suggest BO model
+ else: # `force_random_search` is True or we could not suggest BO model
  if verbose is not None:
  logger.warning(
  f"Ignoring `verbose = {verbose}` for `generation_strategy` "

ax/utils/common/deprecation.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+import warnings
+from typing import Optional, Type
+
+
+def _validate_force_random_search(
+ no_bayesian_optimization: Optional[bool] = None,
+ force_random_search: bool = False,
+ exception_cls: Type[Exception] = ValueError,
+) -> None:
+ if no_bayesian_optimization is not None:
+ # users are effectively permitted to continue using
+ # `no_bayesian_optimization` so long as it doesn't
+ # conflict with `force_random_search`
+ if no_bayesian_optimization != force_random_search:
+ raise exception_cls(
+ "Conflicting values for `force_random_search` "
+ "and `no_bayesian_optimization`! "
+ "Please only specify `force_random_search`."
+ )
+ warnings.warn(
+ "`no_bayesian_optimization` is deprecated. Please use "
+ "`force_random_search` in the future.",
+ DeprecationWarning,
+ stacklevel=2,
+ )