Add DiscreteBatchConstraint

AGENTS.md

@@ -131,6 +131,8 @@ Custom `@classproperty` from `baybe.utils.basic` for class-level computed proper
 - No private field names (`_attr`) in user-facing messages — use
   `fields(type(self)).attr.alias`.
 - Method names start with verbs. Comments capitalize first word.
+- Always capitalize words that correspond to names of inventors, e.g. `Bayesian`,
+  `Boolean` or `Gaussian`
 
 ## 5. Type Annotations
 - **Full coverage**: All signatures including returns. Every field annotated.
@@ -236,7 +238,7 @@ Three tiers:
 - Cache invalidation: `on_setattr` hooks on mutable fields.
 
 ## 12. Optional Dependencies
-1. Detection (`baybe/_optional/info.py`): `importlib.util.find_spec()` sets boolean
+1. Detection (`baybe/_optional/info.py`): `importlib.util.find_spec()` sets Boolean
    flags (`CHEM_INSTALLED`, `ONNX_INSTALLED`, etc.) without importing.
 2. Guarded imports (`baybe/_optional/<dep>.py`): Import or raise
    `OptionalImportError` with pip install instructions.

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Coding convention instructions for agentic developers (`AGENTS.md`, `CLAUDE.md`)
 - `has_polars_implementation` property on `DiscreteConstraint`
 - `allow_missing` flag on `DiscreteConstraint.get_invalid` and `get_valid`
+- `DiscreteBatchConstraint` for ensuring all recommendations in a batch share
+  the same value for a specified discrete parameter
 
 ### Breaking Changes
 - `parameter_cartesian_prod_pandas` and `parameter_cartesian_prod_polars` moved
@@ -26,6 +28,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 - Broken cache validation for certain `Campaign.recommend` cases
+- `ContinuousCardinalityConstraint` now works in hybrid search spaces
+- Typo in `_FixedNumericalContinuousParameter` where `is_numeric` was used
+  instead of `is_numerical`
 - `SHAPInsight` breaking with `numpy>=2.4` due to no longer accepted implicit array to 
   scalar conversion
 - Using `np.isclose` for assessing equality of `Interval` bounds instead of hard
@@ -46,6 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   can now be conveniently controlled via the new `Settings` mechanism
 
 ### Deprecations
+- `BotorchRecommender.max_n_subspaces` has been renamed to `max_n_partitions`
 - `set_random_seed` and `temporary_seed` utility functions
 - The environment variables
   `BAYBE_NUMPY_USE_SINGLE_PRECISION`/`BAYBE_TORCH_USE_SINGLE_PRECISION` have been

baybe/_optional/info.py

@@ -7,7 +7,7 @@
 
 
 @contextmanager
-def exclude_sys_path(path: str, /):  # noqa: DOC402, DOC404
+def exclude_sys_path(path: str, /):  # noqa: DOC402
     """Temporarily remove a specified path from `sys.path`.
 
     Args:

baybe/constraints/__init__.py

@@ -11,6 +11,7 @@
 )
 from baybe.constraints.discrete import (
     DISCRETE_CONSTRAINTS_FILTERING_ORDER,
+    DiscreteBatchConstraint,
     DiscreteCardinalityConstraint,
     DiscreteCustomConstraint,
     DiscreteDependenciesConstraint,
@@ -33,6 +34,7 @@
     "ContinuousLinearEqualityConstraint",
     "ContinuousLinearInequalityConstraint",
     # --- Discrete constraints ---#
+    "DiscreteBatchConstraint",
     "DiscreteCardinalityConstraint",
     "DiscreteCustomConstraint",
     "DiscreteDependenciesConstraint",

baybe/constraints/continuous.py

@@ -203,7 +203,14 @@ def to_botorch(
 class ContinuousCardinalityConstraint(
     CardinalityConstraint, ContinuousNonlinearConstraint
 ):
-    """Class for continuous cardinality constraints."""
+    """Class for continuous cardinality constraints.
+
+    Notes:
+        This constraint can lead to overhead in the computation since optimization
+        results in individual optimizations over several subsets. If there are
+        multiple subset-generating constraints active, this can drastically increase
+        the computational cost due to the combinatorial explosion.
+    """
 
     relative_threshold: float = field(
         default=1e-3, converter=float, validator=[gt(0.0), lt(1.0)]

baybe/constraints/discrete.py

@@ -7,6 +7,8 @@
 from functools import reduce
 from typing import TYPE_CHECKING, Any, ClassVar, cast
 
+import numpy as np
+import numpy.typing as npt
 import pandas as pd
 from attrs import define, field
 from attrs.validators import in_, min_len
@@ -424,6 +426,72 @@ def _get_invalid(self, df: pd.DataFrame, /) -> pd.Index:
         return df.index[mask_bad]
 
 
+@define
+class DiscreteBatchConstraint(DiscreteConstraint):
+    """Constraint ensuring recommendations in a batch share certain parameter values.
+
+    When this constraint is active, the recommender internally subsets the
+    candidate set (one subset for each unique value of the constrained
+    parameter), obtains a full batch recommendation from each subset, and
+    returns the batch with the highest joint acquisition value.
+
+    This constraint is not supported by all recommenders. It is not applied during
+    search space creation (all parameter values remain in the search space).
+
+    Example:
+        If parameter ``Temperature`` has values ``[50, 100, 150]`` and a batch of
+        10 is requested, the recommender will generate three candidate batches
+        (one all-50, one all-100, one all-150) and return the best one.
+
+    Notes:
+        This constraint can lead to overhead in the computation since optimization
+        results in individual optimizations over several subsets. If there are
+        multiple subset-generating constraints active, this can drastically increase
+        the computational cost due to the combinatorial explosion.
+    """
+
+    # Class variables
+    eval_during_creation: ClassVar[bool] = False
+    eval_during_modeling: ClassVar[bool] = True
+    numerical_only: ClassVar[bool] = False
+
+    def __attrs_post_init__(self):
+        """Validate that exactly one parameter is specified."""
+        if len(self.parameters) != 1:
+            raise ValueError(
+                f"'{self.__class__.__name__}' requires exactly one parameter, "
+                f"but {len(self.parameters)} were provided: {self.parameters}."
+            )
+
+    @override
+    def _get_invalid(self, df: pd.DataFrame, /) -> pd.Index:
+        # Always returns an empty index because this constraint operates at the
+        # batch level, not the row level. Individual rows are never invalid; the
+        # constraint is enforced at recommendation time by subsetting candidates
+        # into subsets.
+        return pd.Index([])
+
+    def subset_masks(
+        self, candidates_exp: pd.DataFrame, /
+    ) -> list[npt.NDArray[np.bool_]]:
+        """Return Boolean masks defining the subsets for this constraint.
+
+        Each mask selects the rows in ``candidates_exp`` that belong to one
+        subset, i.e. share the same value for the constrained parameter.
+
+        Args:
+            candidates_exp: The experimental representation of candidate points.
+
+        Returns:
+            A list of Boolean masks, one per unique value of the constrained
+            parameter.
+        """
+        param = self.parameters[0]
+        return [
+            (candidates_exp[param] == v).values for v in candidates_exp[param].unique()
+        ]
+
+
 @define
 class DiscreteCardinalityConstraint(CardinalityConstraint, DiscreteConstraint):
     """Class for discrete cardinality constraints."""
@@ -466,6 +534,7 @@ def _get_invalid(self, df: pd.DataFrame, /) -> pd.Index:
     DiscreteCustomConstraint,
     DiscretePermutationInvarianceConstraint,
     DiscreteDependenciesConstraint,
+    DiscreteBatchConstraint,
 )
 
 # Prevent (de-)serialization of custom constraints

baybe/constraints/validation.py

@@ -6,6 +6,7 @@
 from baybe.constraints.base import Constraint
 from baybe.constraints.continuous import ContinuousCardinalityConstraint
 from baybe.constraints.discrete import (
+    DiscreteBatchConstraint,
     DiscreteDependenciesConstraint,
 )
 from baybe.parameters import NumericalContinuousParameter
@@ -27,6 +28,7 @@ def validate_constraints(  # noqa: DOC101, DOC103
             :class:`baybe.constraints.discrete.DiscreteDependenciesConstraint` declared.
         ValueError: If any two continuous cardinality constraints have an overlapping
             parameter set.
+        ValueError: If multiple batch constraints reference the same parameter.
         ValueError: If any constraint contains an invalid parameter name.
         ValueError: If any continuous constraint includes a discrete parameter.
         ValueError: If any discrete constraint includes a continuous parameter.
@@ -45,6 +47,16 @@ def validate_constraints(  # noqa: DOC101, DOC103
         [con for con in constraints if isinstance(con, ContinuousCardinalityConstraint)]
     )
 
+    batch_param_names = [
+        c.parameters[0] for c in constraints if isinstance(c, DiscreteBatchConstraint)
+    ]
+    if duplicates := {n for n in batch_param_names if batch_param_names.count(n) > 1}:
+        raise ValueError(
+            f"Multiple '{DiscreteBatchConstraint.__name__}' instances reference "
+            f"the same parameter(s): {duplicates}. Each parameter can have at "
+            f"most one batch constraint."
+        )
+
     param_names_all = [p.name for p in parameters]
     param_names_discrete = [p.name for p in parameters if p.is_discrete]
     param_names_continuous = [p.name for p in parameters if p.is_continuous]

baybe/parameters/numerical.py

@@ -155,7 +155,7 @@ def summary(self) -> dict:
 class _FixedNumericalContinuousParameter(ContinuousParameter):
     """Parameter class for fixed numerical parameters."""
 
-    is_numeric: ClassVar[bool] = True
+    is_numerical: ClassVar[bool] = True
     # See base class.
 
     value: float = field(converter=float)

baybe/recommenders/naive.py

@@ -41,11 +41,11 @@ class NaiveHybridSpaceRecommender(PureRecommender):
     # problem that might come up when implementing new subclasses of PureRecommender
     disc_recommender: PureRecommender = field(factory=BotorchRecommender)
     """The recommender used for the discrete subspace. Default:
-    :class:`baybe.recommenders.pure.bayesian.botorch.BotorchRecommender`"""
+    :class:`baybe.recommenders.pure.bayesian.botorch.core.BotorchRecommender`"""
 
     cont_recommender: BayesianRecommender = field(factory=BotorchRecommender)
     """The recommender used for the continuous subspace. Default:
-    :class:`baybe.recommenders.pure.bayesian.botorch.BotorchRecommender`"""
+    :class:`baybe.recommenders.pure.bayesian.botorch.core.BotorchRecommender`"""
 
     @override
     def recommend(

baybe/recommenders/pure/base.py

@@ -11,7 +11,11 @@
 from cattrs.gen import make_dict_unstructure_fn
 from typing_extensions import override
 
-from baybe.exceptions import DeprecationError, NotEnoughPointsLeftError
+from baybe.exceptions import (
+    DeprecationError,
+    IncompatibilityError,
+    NotEnoughPointsLeftError,
+)
 from baybe.objectives.base import Objective
 from baybe.recommenders.base import RecommenderProtocol
 from baybe.searchspace import SearchSpace
@@ -38,6 +42,10 @@ class PureRecommender(ABC, RecommenderProtocol):
     compatibility: ClassVar[SearchSpaceType]
     """Class variable reflecting the search space compatibility."""
 
+    supports_discrete_batch_constraints: ClassVar[bool] = False
+    """Class variable indicating whether the recommender supports discrete
+    batch constraints."""
+
     _deprecated_allow_repeated_recommendations: bool = field(
         alias="allow_repeated_recommendations",
         default=None,
@@ -259,6 +267,20 @@ def _recommend_with_discrete_parts(
         """
         is_hybrid_space = searchspace.type is SearchSpaceType.HYBRID
 
+        # Check batch constraint support
+        if (
+            searchspace.discrete.constraints_batch
+            and not self.supports_discrete_batch_constraints
+        ):
+            constraint_types = {
+                type(c).__name__ for c in searchspace.discrete.constraints_batch
+            }
+            raise IncompatibilityError(
+                f"'{self.__class__.__name__}' does not support discrete "
+                f"batch constraints. The search space contains: "
+                f"{constraint_types}."
+            )
+
         # Get discrete candidates
         candidates_exp, _ = searchspace.discrete.get_candidates()