Rename parallelism to concurrency in Client and AxClient APIs

Summary: Renames the `parallelism` parameter to `concurrency` in `Client.run_trials()` and adds backward-compatible deprecated `max_parallelism` parameters in `AxClient.create_experiment()` and `AxClient.get_max_parallelism()` → `get_max_concurrency()`. Both include deprecation warnings guiding callers to use the new parameter names, with validation that old and new parameters are not specified simultaneously.

Differential Revision: D93771849

Author: mgrange1998

ax/api/client.py

@@ -6,6 +6,7 @@
 # pyre-strict
 
 import json
+import warnings
 from collections.abc import Iterable, Sequence
 from logging import Logger
 from typing import Any, Literal, Self
@@ -43,7 +44,7 @@
     BaseEarlyStoppingStrategy,
     PercentileEarlyStoppingStrategy,
 )
-from ax.exceptions.core import ObjectNotFoundError, UnsupportedError
+from ax.exceptions.core import ObjectNotFoundError, UnsupportedError, UserInputError
 from ax.generation_strategy.generation_strategy import GenerationStrategy
 from ax.orchestration.orchestrator import Orchestrator, OrchestratorOptions
 from ax.service.utils.best_point_mixin import BestPointMixin
@@ -710,9 +711,11 @@ def mark_trial_early_stopped(self, trial_index: int) -> None:
     def run_trials(
         self,
         max_trials: int,
-        parallelism: int = 1,
+        concurrency: int = 1,
         tolerated_trial_failure_rate: float = 0.5,
         initial_seconds_between_polls: int = 1,
+        # Deprecated argument for backwards compatibility.
+        parallelism: int | None = None,
     ) -> None:
         """
         Run maximum_trials trials in a loop by creating an ephemeral Orchestrator under
@@ -721,12 +724,25 @@ def run_trials(
 
         Saves to database on completion if ``storage_config`` is present.
         """
+        # Handle deprecated `parallelism` argument.
+        if parallelism is not None:
+            warnings.warn(
+                "`parallelism` is deprecated and will be removed in Ax 1.4. "
+                "Use `concurrency` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if concurrency != 1:
+                raise UserInputError(
+                    "Cannot specify both `parallelism` and `concurrency`."
+                )
+            concurrency = parallelism
 
         orchestrator = Orchestrator(
             experiment=self._experiment,
             generation_strategy=self._generation_strategy_or_choose(),
             options=OrchestratorOptions(
-                max_pending_trials=parallelism,
+                max_pending_trials=concurrency,
                 tolerated_trial_failure_rate=tolerated_trial_failure_rate,
                 init_seconds_between_polls=initial_seconds_between_polls,
             ),

ax/service/ax_client.py

@@ -836,39 +836,39 @@ def get_trials_data_frame(self) -> pd.DataFrame:
         """
         return self.experiment.to_df()
 
-    def get_max_parallelism(self) -> list[tuple[int, int]]:
-        """Retrieves maximum number of trials that can be scheduled in parallel
+    def get_max_concurrency(self) -> list[tuple[int, int]]:
+        """Retrieves maximum number of trials that can be scheduled concurrently
         at different stages of optimization.
 
         Some optimization algorithms profit significantly from sequential
         optimization (i.e. suggest a few points, get updated with data for them,
         repeat, see https://ax.dev/docs/bayesopt.html).
-        Parallelism setting indicates how many trials should be running simulteneously
+        Concurrency setting indicates how many trials should be running simultaneously
         (generated, but not yet completed with data).
 
         The output of this method is mapping of form
-        {num_trials -> max_parallelism_setting}, where the max_parallelism_setting
-        is used for num_trials trials. If max_parallelism_setting is -1, as
-        many of the trials can be ran in parallel, as necessary. If num_trials
-        in a tuple is -1, then the corresponding max_parallelism_setting
+        {num_trials -> max_concurrency_setting}, where the max_concurrency_setting
+        is used for num_trials trials. If max_concurrency_setting is -1, as
+        many of the trials can be ran concurrently, as necessary. If num_trials
+        in a tuple is -1, then the corresponding max_concurrency_setting
         should be used for all subsequent trials.
 
         For example, if the returned list is [(5, -1), (12, 6), (-1, 3)],
-        the schedule could be: run 5 trials with any parallelism, run 6 trials in
-        parallel twice, run 3 trials in parallel for as long as needed. Here,
+        the schedule could be: run 5 trials with any concurrency, run 6 trials
+        concurrently twice, run 3 trials concurrently for as long as needed. Here,
         'running' a trial means obtaining a next trial from `AxClient` through
         get_next_trials and completing it with data when available.
 
         Returns:
-            Mapping of form {num_trials -> max_parallelism_setting}.
+            Mapping of form {num_trials -> max_concurrency_setting}.
         """
-        parallelism_settings = []
+        concurrency_settings = []
         for node in self.generation_strategy._nodes:
-            # Extract max_parallelism from MaxGenerationParallelism criterion
-            max_parallelism = None
+            # Extract max_concurrency from MaxGenerationParallelism criterion
+            max_concurrency = None
             for tc in node.transition_criteria:
                 if isinstance(tc, MaxGenerationParallelism):
-                    max_parallelism = tc.threshold
+                    max_concurrency = tc.threshold
                     break
             # Try to get num_trials from the node. If there's no MinTrials
             # criterion (unlimited trials), num_trials will raise UserInputError.
@@ -877,13 +877,23 @@ def get_max_parallelism(self) -> list[tuple[int, int]]:
                 num_trials = node.num_trials
             except UserInputError:
                 num_trials = -1
-            parallelism_settings.append(
+            concurrency_settings.append(
                 (
                     num_trials,
-                    max_parallelism if max_parallelism is not None else num_trials,
+                    max_concurrency if max_concurrency is not None else num_trials,
                 )
             )
-        return parallelism_settings
+        return concurrency_settings
+
+    def get_max_parallelism(self) -> list[tuple[int, int]]:
+        """Deprecated. Use `get_max_concurrency` instead."""
+        warnings.warn(
+            "`get_max_parallelism` is deprecated and will be removed in Ax 1.4. "
+            "Use `get_max_concurrency` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_max_concurrency()
 
     def get_optimization_trace(
         self, objective_optimum: float | None = None

ax/service/tests/test_ax_client.py

@@ -50,7 +50,7 @@
     UserInputError,
 )
 from ax.exceptions.generation_strategy import MaxParallelismReachedException
-from ax.generation_strategy.dispatch_utils import DEFAULT_BAYESIAN_PARALLELISM
+from ax.generation_strategy.dispatch_utils import DEFAULT_BAYESIAN_CONCURRENCY
 from ax.generation_strategy.generation_strategy import (
     GenerationNode,
     GenerationStep,
@@ -511,7 +511,7 @@ def test_default_generation_strategy_continuous(self) -> None:
             if i < 5:
                 self.assertEqual(gen_limit, 5 - i)
             else:
-                self.assertEqual(gen_limit, DEFAULT_BAYESIAN_PARALLELISM)
+                self.assertEqual(gen_limit, DEFAULT_BAYESIAN_CONCURRENCY)
             parameterization, trial_index = ax_client.get_next_trial()
             x, y = parameterization.get("x"), parameterization.get("y")
             ax_client.complete_trial(
@@ -1616,14 +1616,14 @@ def test_keep_generating_without_data(self) -> None:
         self.assertTrue(len(node0_min_trials) > 0)
         self.assertFalse(node0_min_trials[0].block_gen_if_met)
 
-        # Check that max_parallelism is None by verifying no MaxGenerationParallelism
+        # Check that max_concurrency is None by verifying no MaxGenerationParallelism
         # criterion exists on node 1
-        node1_max_parallelism = [
+        node1_max_concurrency = [
             tc
             for tc in ax_client.generation_strategy._nodes[1].transition_criteria
             if isinstance(tc, MaxGenerationParallelism)
         ]
-        self.assertEqual(len(node1_max_parallelism), 0)
+        self.assertEqual(len(node1_max_concurrency), 0)
 
         for _ in range(10):
             ax_client.get_next_trial()
@@ -1939,17 +1939,17 @@ def test_relative_oc_without_sq(self) -> None:
     def test_recommended_parallelism(self) -> None:
         ax_client = AxClient()
         with self.assertRaisesRegex(AssertionError, "No generation strategy"):
-            ax_client.get_max_parallelism()
+            ax_client.get_max_concurrency()
         ax_client.create_experiment(
             parameters=[
                 {"name": "x", "type": "range", "bounds": [-5.0, 10.0]},
                 {"name": "y", "type": "range", "bounds": [0.0, 15.0]},
             ],
         )
-        self.assertEqual(ax_client.get_max_parallelism(), [(5, 5), (-1, 3)])
+        self.assertEqual(ax_client.get_max_concurrency(), [(5, 5), (-1, 3)])
         self.assertEqual(
             run_trials_using_recommended_parallelism(
-                ax_client, ax_client.get_max_parallelism(), 20
+                ax_client, ax_client.get_max_concurrency(), 20
             ),
             0,
         )
@@ -2872,7 +2872,7 @@ def test_estimate_early_stopping_savings(self) -> None:
 
         self.assertEqual(ax_client.estimate_early_stopping_savings(), 0)
 
-    def test_max_parallelism_exception_when_early_stopping(self) -> None:
+    def test_max_concurrency_exception_when_early_stopping(self) -> None:
         ax_client = AxClient()
         ax_client.create_experiment(
             parameters=[