Botorch with cardinality constraint via sampling

CHANGELOG.md

@@ -13,6 +13,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 – `Campaign.toggle_discrete_candidates` to dynamically in-/exclude discrete candidates
 - `DiscreteConstraint.get_valid` to conveniently access valid candidates
 - Functionality for persisting benchmarking results on S3 from a manual pipeline run
+- `ContinuousCardinalityConstraint` is now compatible with `BotorchRecommender`
+- Warning `MinimumCardinalityViolatedWarning` is triggered when any minimum 
+  cardinality is violated in `BotorchRecommender`
+- Attribute `max_n_subspaces` to `BotorchRecommender`, allowing to control
+  optimization behavior in the presence of multiple subspaces
+- Utilities `inactive_parameter_combinations` and`n_inactive_parameter_combinations` 
+  in both `ContinuousCardinalityConstraint`and `SubspaceContinuous`
+- Attribute `near_zero_threshold` and utility `is_near_zero` to 
+  `NumericalContinuousParameter`
+- Utilities `count_near_zeros` and `is_min_cardinality_fulfilled`
 
 ### Changed
 - `SubstanceParameter` encodings are now computed exclusively with the

README.md

@@ -37,6 +37,7 @@ Besides functionality to perform a typical recommend-measure loop, BayBE's highl
 - 🎭 Hybrid (mixed continuous and discrete) spaces
 - 🚀 Transfer learning: Mix data from multiple campaigns and accelerate optimization
 - 🎰 Bandit models: Efficiently find the best among many options in noisy environments (e.g. A/B Testing)
+- 🔢 Cardinality constraints: Control the number of active factors in your design
 - 🌎 Distributed workflows: Run campaigns asynchronously with pending experiments
 - 🎓 Active learning: Perform smart data acquisition campaigns
 - ⚙️ Custom surrogate models: Enhance your predictions through mechanistic understanding

baybe/constraints/continuous.py

@@ -4,7 +4,9 @@
 
 import gc
 import math
-from collections.abc import Collection, Sequence
+from collections.abc import Collection, Iterator, Sequence
+from itertools import combinations
+from math import comb
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
@@ -138,6 +140,26 @@ class ContinuousCardinalityConstraint(
 ):
     """Class for continuous cardinality constraints."""
 
+    @property
+    def n_inactive_parameter_combinations(self) -> int:
+        """The number of possible inactive parameter combinations."""
+        return sum(
+            comb(len(self.parameters), n_inactive_parameters)
+            for n_inactive_parameters in self._inactive_set_sizes()
+        )
+
+    def _inactive_set_sizes(self) -> range:
+        """Get all possible sizes of inactive parameter sets."""
+        return range(
+            len(self.parameters) - self.max_cardinality,
+            len(self.parameters) - self.min_cardinality + 1,
+        )
+
+    def inactive_parameter_combinations(self) -> Iterator[frozenset[str]]:
+        """Get an iterator over all possible combinations of inactive parameters."""
+        for n_inactive_parameters in self._inactive_set_sizes():
+            yield from combinations(self.parameters, n_inactive_parameters)
+
     def sample_inactive_parameters(self, batch_size: int = 1) -> list[set[str]]:
         """Sample sets of inactive parameters according to the cardinality constraints.
 

baybe/constraints/validation.py

@@ -8,8 +8,14 @@
 from baybe.constraints.discrete import (
     DiscreteDependenciesConstraint,
 )
+from baybe.parameters import NumericalContinuousParameter
 from baybe.parameters.base import Parameter
 
+try:  # For python < 3.11, use the exceptiongroup backport
+    ExceptionGroup
+except NameError:
+    from exceptiongroup import ExceptionGroup
+
 
 def validate_constraints(  # noqa: DOC101, DOC103
     constraints: Collection[Constraint], parameters: Collection[Parameter]
@@ -26,6 +32,8 @@ def validate_constraints(  # noqa: DOC101, DOC103
         ValueError: If any discrete constraint includes a continuous parameter.
         ValueError: If any discrete constraint that is valid only for numerical
             discrete parameters includes non-numerical discrete parameters.
+        ValueError: If any parameter affected by a cardinality constraint does
+            not include zero.
     """
     if sum(isinstance(itm, DiscreteDependenciesConstraint) for itm in constraints) > 1:
         raise ValueError(
@@ -41,6 +49,9 @@ def validate_constraints(  # noqa: DOC101, DOC103
     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]
     param_names_non_numerical = [p.name for p in parameters if not p.is_numerical]
+    params_continuous: list[NumericalContinuousParameter] = [
+        p for p in parameters if isinstance(p, NumericalContinuousParameter)
+    ]
 
     for constraint in constraints:
         if not all(p in param_names_all for p in constraint.parameters):
@@ -78,6 +89,11 @@ def validate_constraints(  # noqa: DOC101, DOC103
                 f"Parameter list of the affected constraint: {constraint.parameters}."
             )
 
+        if isinstance(constraint, ContinuousCardinalityConstraint):
+            validate_cardinality_constraint_parameter_bounds(
+                constraint, params_continuous
+            )
+
 
 def validate_cardinality_constraints_are_nonoverlapping(
     constraints: Collection[ContinuousCardinalityConstraint],
@@ -98,3 +114,44 @@ def validate_cardinality_constraints_are_nonoverlapping(
                 f"cannot share the same parameters. Found the following overlapping "
                 f"parameter sets: {s1}, {s2}."
             )
+
+
+def validate_cardinality_constraint_parameter_bounds(
+    constraint: ContinuousCardinalityConstraint,
+    parameters: Collection[NumericalContinuousParameter],
+) -> None:
+    """Validate that all parameters of a continuous cardinality constraint include zero.
+
+    Args:
+        constraint: A continuous cardinality constraint.
+        parameters: A collection of parameters, including those affected by the
+            constraint.
+
+    Raises:
+        ValueError: If one of the affected parameters does not include zero.
+        ExceptionGroup: If several of the affected parameters do not include zero.
+    """
+    exceptions = []
+    for name in constraint.parameters:
+        try:
+            parameter = next(p for p in parameters if p.name == name)
+        except StopIteration as ex:
+            raise ValueError(
+                f"The parameter '{name}' referenced by the constraint is not contained "
+                f"in the given collection of parameters."
+            ) from ex
+
+        if not parameter.is_in_range(0.0):
+            exceptions.append(
+                ValueError(
+                    f"The bounds of all parameters affected by a constraint of type "
+                    f"'{ContinuousCardinalityConstraint.__name__}' must include zero, "
+                    f"but the bounds of parameter '{name}' are: "
+                    f"{parameter.bounds.to_tuple()}"
+                )
+            )
+
+    if exceptions:
+        if len(exceptions) == 1:
+            raise exceptions[0]
+        raise ExceptionGroup("Invalid parameter bounds", exceptions)

baybe/exceptions.py

@@ -9,6 +9,10 @@ class UnusedObjectWarning(UserWarning):
     """
 
 
+class MinimumCardinalityViolatedWarning(UserWarning):
+    """Minimum cardinality constraints are violated."""
+
+
 ##### Exceptions #####
 
 

baybe/parameters/numerical.py

@@ -112,6 +112,9 @@ class NumericalContinuousParameter(ContinuousParameter):
     bounds: Interval = field(default=None, converter=convert_bounds)
     """The bounds of the parameter."""
 
+    near_zero_threshold: float = field(default=1e-5, converter=float)
+    """A threshold for determining if the value is considered near-zero."""
+
     @bounds.validator
     def _validate_bounds(self, _: Any, value: Interval) -> None:  # noqa: DOC101, DOC103
         """Validate bounds.
@@ -149,6 +152,54 @@ def summary(self) -> dict:
         )
         return param_dict
 
+    def is_near_zero(self, item: float) -> bool:
+        """Return whether an item is near-zero.
+
+        Important:
+            Value in the open interval (-near_zero_threshold, near_zero_threshold)
+            will be treated as near_zero.
+
+        Args:
+            item: The value to be checked.
+
+        Returns:
+            ``True`` if the value is near-zero, ``False`` otherwise.
+        """
+        return abs(item) < self.near_zero_threshold
+
+
+@define(frozen=True, slots=False)
+class _FixedNumericalContinuousParameter(ContinuousParameter):
+    """Parameter class for fixed numerical parameters."""
+
+    is_numeric: ClassVar[bool] = True
+    # See base class.
+
+    value: float = field(converter=float)
+    """The fixed value of the parameter."""
+
+    @property
+    def bounds(self) -> Interval:
+        """The value of the parameter as a degenerate interval."""
+        return Interval(self.value, self.value)
+
+    @override
+    def is_in_range(self, item: float) -> bool:
+        return item == self.value
+
+    @override
+    @property
+    def comp_rep_columns(self) -> tuple[str, ...]:
+        return (self.name,)
+
+    @override
+    def summary(self) -> dict:
+        return dict(
+            Name=self.name,
+            Type=self.__class__.__name__,
+            Value=self.value,
+        )
+
 
 # Collect leftover original slotted classes processed by `attrs.define`
 gc.collect()

baybe/parameters/utils.py

@@ -4,8 +4,10 @@
 from typing import Any, TypeVar
 
 import pandas as pd
+from attrs import evolve
 
 from baybe.parameters.base import Parameter
+from baybe.parameters.numerical import NumericalContinuousParameter
 
 _TParameter = TypeVar("_TParameter", bound=Parameter)
 
@@ -87,3 +89,48 @@ def get_parameters_from_dataframe(
 def sort_parameters(parameters: Collection[Parameter]) -> tuple[Parameter, ...]:
     """Sort parameters alphabetically by their names."""
     return tuple(sorted(parameters, key=lambda p: p.name))
+
+
+def activate_parameter(
+    parameter: NumericalContinuousParameter,
+) -> NumericalContinuousParameter:
+    """Activates a given parameter by moving its bounds away from zero.
+
+    Important:
+        Parameters whose ranges include zero but whose bounds do not overlap with the
+        inactive range (i.e. parameters that contain the value zero far from their
+        boundary values) remain unchanged, because the corresponding activated parameter
+        would no longer have a continuous value range.
+
+    Args:
+        parameter: The parameter to be activated.
+
+    Returns:
+        A copy of the parameter with adjusted bounds.
+
+    Raises:
+        ValueError: If the parameter cannot be activated since both its bounds are
+            in the inactive range.
+    """
+    lower = parameter.bounds.lower
+    upper = parameter.bounds.upper
+
+    # Upper bound is in near-zero range
+    if lower <= -parameter.near_zero_threshold and parameter.is_near_zero(upper):
+        return evolve(parameter, bounds=(lower, -parameter.near_zero_threshold))
+
+    # Lower bound is in near-zero range
+    if upper > parameter.near_zero_threshold and parameter.is_near_zero(lower):
+        return evolve(parameter, bounds=(parameter.near_zero_threshold, upper))
+
+    # Both bounds in inactive range
+    if parameter.is_near_zero(lower) and parameter.is_near_zero(upper):
+        raise ValueError(
+            f"Parameter '{parameter.name}' cannot be set active since its "
+            f"bounds {parameter.bounds.to_tuple()} are entirely contained in the "
+            f"inactive range [-{parameter.near_zero_threshold},"
+            f" {parameter.near_zero_threshold}]."
+        )
+
+    # Both bounds separated from inactive range
+    return parameter