Refactor candidates interface (#840)

Preparation to fix #795, #796 and #798.

### Background

As part of the broader effort toward lazy, on-demand evaluation of
candidate sets (see linked issues), this PR removes the dependency on
the eagerly pre-computed, fully materialized `exp_rep` and `comp_rep`
public attributes of `SubspaceDiscrete`. The old design forced the full
candidate space to be computed and cached upfront, even when only a
subset is needed — blocking future subsampling policies and
backend-agnostic mechanisms required for handling large spaces.

The key step is giving `get_candidates` a clean, single-purpose method
signature as the sole access point for the experimental representation,
so that transformation into the computational representation happens
only when explicitly requested and only on the relevant data (the subset
selection will be enabled later).

### Out of scope

The return type of `get_candidates` is expected to be elevated to a
higher-level object in a follow-up (e.g. `TableCandidates` or a similar
abstraction). This PR deliberately keeps the return type as
`pd.DataFrame` to stay focused on the interface decoupling.

### Changes

**Make `exp_rep` private** (`baybe/searchspace/discrete.py`)
Renames the field to `_exp_rep` (with `alias="exp_rep"` for
serialization compatibility), updates the validator reference, and
replaces all internal accesses.

**Simplify `get_candidates` signature**
(`baybe/searchspace/discrete.py`)
Returns only the experimental representation (`pd.DataFrame`) instead of
a `tuple[pd.DataFrame, pd.DataFrame]`, avoiding wasteful upfront
computation of the computational representation.

**Update all internal call sites** (`baybe/campaign.py`,
`baybe/recommenders/`, `baybe/simulation/`, `baybe/searchspace/core.py`,
`baybe/acquisition/`)
Replaces tuple-unpacking calls to `get_candidates` and direct
`exp_rep`/`comp_rep` accesses with the new API throughout. Computational
representation is now computed on-demand, at the point of use.

**Update examples and tests** (`examples/`, `tests/`)
Adapts all affected examples and tests to the new `get_candidates`
return type.

**Deprecate `exp_rep` and `comp_rep` properties**
(`baybe/searchspace/discrete.py`)
Adds `DeprecationWarning` shims for `exp_rep` (pointing to
`get_candidates()`) and `comp_rep` (pointing to
`transform(get_candidates())`), with corresponding deprecation tests.

Author: AdrianSosic

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `candidates_exp` argument removed from `SubspaceDiscrete.subset_masks`,
   `SubspaceDiscrete.sample_subset_masks`, `SearchSpace.subsets`, and
   `SearchSpace.sample_subsets`
+- `SubspaceDiscrete.get_candidates` now returns only the experimental representation
+  instead of a tuple of experimental and computational representations
 
 ### Added
 - `narwhals` as a hard dependency
@@ -50,6 +52,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   access batch-level constraints; filtering constraints are only needed during subspace
   construction and are thus no longer stored).
 - `SubspaceDiscrete.constraints_batch` property (use `batch_constraints` instead)
+- `SubspaceDiscrete.exp_rep` attribute (use `get_candidates()` instead)
+- `SubspaceDiscrete.comp_rep` attribute (use `transform(get_candidates())` instead)
 
 ## [0.15.0] - 2026-06-11
 ### Breaking Changes

baybe/acquisition/acqfs.py

@@ -104,7 +104,9 @@ def get_integration_points(self, searchspace: SearchSpace) -> pd.DataFrame:
 
         # Discrete part
         if not searchspace.discrete.is_empty:
-            candidates_discrete = searchspace.discrete.comp_rep
+            candidates_discrete = searchspace.discrete.transform(
+                searchspace.discrete.get_candidates()
+            )
             n_candidates = self.sampling_n_points or math.ceil(
                 self.sampling_fraction * len(candidates_discrete)  # type: ignore[operator]
             )

baybe/campaign.py

@@ -206,39 +206,7 @@ def _default_recommended_experiments(self) -> pd.DataFrame:
 
     @override
     def __str__(self) -> str:
-        recommended_count = len(self._recommended_experiments)
-        exp_rep = self.searchspace.discrete.exp_rep
-        if self._measurements.empty or exp_rep.empty:
-            measured_count = 0
-        else:
-            measured_count = len(
-                fuzzy_row_match(exp_rep, self._measurements, self.parameters)
-            )
-        excluded_count = len(self._excluded_experiments)
-        n_elements = len(exp_rep)
-        searchspace_fields = [
-            to_string(
-                "Recommended:",
-                f"{recommended_count}/{n_elements}",
-                single_line=True,
-            ),
-            to_string(
-                "Measured:",
-                f"{measured_count}/{n_elements}",
-                single_line=True,
-            ),
-            to_string(
-                "Excluded:",
-                f"{excluded_count}/{n_elements}",
-                single_line=True,
-            ),
-        ]
-        metadata_fields = [
-            to_string("Discrete Subspace Meta Data", *searchspace_fields),
-        ]
-        metadata = to_string("Meta Data", *metadata_fields)
-        fields = [metadata, self.searchspace, self.objective, self.recommender]
-
+        fields = [self.searchspace, self.objective, self.recommender]
         return to_string(self.__class__.__name__, *fields)
 
     @property
@@ -460,7 +428,7 @@ def toggle_discrete_candidates(  # noqa: DOC501
         #  * Additional shortcuts might be possible.
         self.clear_cache()
 
-        df = self.searchspace.discrete.exp_rep
+        df = self.searchspace.discrete.get_candidates()
 
         if isinstance(constraints, pd.DataFrame):
             # Determine the candidate subset to be toggled
@@ -561,12 +529,12 @@ def recommend(
         if self.searchspace.type is SearchSpaceType.DISCRETE:
             # TODO: This implementation should at some point be hidden behind an
             #   appropriate public interface, like `SubspaceDiscrete.filter()`
-            exp_rep = self.searchspace.discrete.exp_rep
-            mask_todrop = pd.Series(False, index=exp_rep.index)
+            candidates = self.searchspace.discrete.get_candidates()
+            mask_todrop = pd.Series(False, index=candidates.index)
             if not self._excluded_experiments.empty:
                 mask_todrop |= (
                     pd.merge(
-                        exp_rep,
+                        candidates,
                         self._excluded_experiments,
                         indicator=True,
                         how="left",
@@ -580,7 +548,7 @@ def recommend(
             ):
                 mask_todrop |= (
                     pd.merge(
-                        exp_rep,
+                        candidates,
                         self._recommended_experiments,
                         indicator=True,
                         how="left",
@@ -593,7 +561,7 @@ def recommend(
                 and not self._measurements.empty
             ):
                 measured_idxs = fuzzy_row_match(
-                    exp_rep, self._measurements, self.parameters
+                    candidates, self._measurements, self.parameters
                 )
                 mask_todrop.loc[measured_idxs] = True
             if (
@@ -602,7 +570,7 @@ def recommend(
             ):
                 mask_todrop |= (
                     pd.merge(
-                        exp_rep,
+                        candidates,
                         pending_experiments,
                         indicator=True,
                         how="left",
@@ -613,7 +581,7 @@ def recommend(
             searchspace = evolve(
                 self.searchspace,
                 discrete=evolve(
-                    self.searchspace.discrete, exp_rep=exp_rep.loc[~mask_todrop]
+                    self.searchspace.discrete, exp_rep=candidates.loc[~mask_todrop]
                 ),
             )
         else:
@@ -1100,13 +1068,16 @@ def _structure_campaign(d: dict, cl: type) -> Campaign:
 
     # >>>>>>>>>> Deprecation
     # Post-structure reconstruction from legacy metadata indices
-    if legacy_recommended_idxs is not None:
-        rec_df = campaign.searchspace.discrete.exp_rep.loc[legacy_recommended_idxs]
-        campaign._recommended_experiments = rec_df.reset_index(drop=True)
-
-    if legacy_excluded_idxs is not None:
-        excl_df = campaign.searchspace.discrete.exp_rep.loc[legacy_excluded_idxs]
-        campaign._excluded_experiments = excl_df.reset_index(drop=True)
+    if legacy_recommended_idxs is not None or legacy_excluded_idxs is not None:
+        candidates = campaign.searchspace.discrete.get_candidates()
+        if legacy_recommended_idxs is not None:
+            campaign._recommended_experiments = candidates.loc[
+                legacy_recommended_idxs
+            ].reset_index(drop=True)
+        if legacy_excluded_idxs is not None:
+            campaign._excluded_experiments = candidates.loc[
+                legacy_excluded_idxs
+            ].reset_index(drop=True)
 
     # Fix schema of empty DataFrames from legacy serialization
     if campaign._measurements.columns.empty:

baybe/recommenders/naive.py

@@ -117,7 +117,7 @@ def recommend(
 
         # Get one random discrete point that will be attached when evaluating the
         # acquisition function in the discrete space.
-        disc_part = searchspace.discrete.comp_rep.loc[disc_rec.index].sample(1)
+        disc_part = searchspace.discrete.transform(disc_rec).sample(1)
         disc_part_tensor = to_tensor(disc_part).unsqueeze(-2)
 
         # Setup a fresh acquisition function for the continuous recommender

baybe/recommenders/pure/base.py

@@ -271,7 +271,9 @@ def _recommend_with_discrete_parts(
 
         # Check if enough candidates are left
         # TODO [15917]: This check is not perfectly correct.
-        if (not is_hybrid_space) and (len(searchspace.discrete.exp_rep) < batch_size):
+        if (not is_hybrid_space) and (
+            len(searchspace.discrete.get_candidates()) < batch_size
+        ):
             raise NotEnoughPointsLeftError(
                 f"Using the current settings, there are fewer than {batch_size} "
                 f"possible data points left to recommend."

baybe/recommenders/pure/bayesian/botorch/discrete.py

@@ -43,6 +43,7 @@ def recommend_discrete_with_subsets(
     """
     import torch
 
+    candidates = subspace_discrete.get_candidates()
     masks: Iterable[npt.NDArray[np.bool_]]
     if subspace_discrete.n_subsets <= recommender.max_n_subsets:
         masks = subspace_discrete.subset_masks(min_candidates=batch_size)
@@ -56,9 +57,7 @@ def make_callable(
         mask: np.ndarray,
     ) -> Callable[[], tuple[pd.DataFrame, Tensor]]:
         def optimize() -> tuple[pd.DataFrame, Tensor]:
-            subset_subspace = evolve(
-                subspace_discrete, exp_rep=subspace_discrete.exp_rep.loc[mask]
-            )
+            subset_subspace = evolve(subspace_discrete, exp_rep=candidates.loc[mask])
 
             rec = recommend_discrete_without_subsets(
                 recommender, subset_subspace, batch_size
@@ -118,7 +117,8 @@ def recommend_discrete_without_subsets(
     from botorch.optim import optimize_acqf_discrete
 
     # Determine the next set of points to be tested
-    candidates_comp = subspace_discrete.comp_rep
+    candidates = subspace_discrete.get_candidates()
+    candidates_comp = subspace_discrete.transform(candidates)
     points, _ = optimize_acqf_discrete(
         recommender._botorch_acqf, batch_size, to_tensor(candidates_comp)
     )
@@ -137,4 +137,4 @@ def recommend_discrete_without_subsets(
         )["index"]
     )
 
-    return subspace_discrete.exp_rep.loc[idxs]
+    return candidates.loc[idxs]

baybe/recommenders/pure/bayesian/botorch/hybrid.py

@@ -81,8 +81,8 @@ def recommend_hybrid_without_subsets(
     from botorch.optim import optimize_acqf_mixed
 
     # Transform discrete candidates
-    # (Create a shallow copy to avoid in-place modifications of the original dataframe)
-    candidates_comp = searchspace.discrete.comp_rep.copy(deep=False)
+    candidates = searchspace.discrete.get_candidates()
+    candidates_comp = searchspace.discrete.transform(candidates)
 
     # Calculate the number of samples from the given percentage
     n_candidates = math.ceil(
@@ -144,7 +144,7 @@ def recommend_hybrid_without_subsets(
     ).set_index("index")
 
     # Get experimental representation of discrete part
-    rec_disc_exp = searchspace.discrete.exp_rep.loc[merged.index]
+    rec_disc_exp = candidates.loc[merged.index]
 
     # Combine discrete and continuous parts
     rec_exp = pd.concat(
@@ -186,6 +186,7 @@ def recommend_hybrid_with_subsets(
     # NOTE: No min_discrete_candidates filtering in hybrid spaces because
     # optimize_acqf_mixed can produce multiple recommendations from a single
     # discrete candidate by varying continuous parameters.
+    candidates = searchspace.discrete.get_candidates()
     combined_masks: Iterable[tuple[np.ndarray, frozenset[str]]]
     if searchspace.n_subsets <= recommender.max_n_subsets:
         combined_masks = searchspace.subsets()
@@ -201,7 +202,7 @@ def optimize() -> tuple[pd.DataFrame, Tensor]:
 
             mod_disc = evolve(
                 searchspace.discrete,
-                exp_rep=searchspace.discrete.exp_rep.loc[d_mask],
+                exp_rep=candidates.loc[d_mask],
             )
             mod_cont = (
                 subspace_c._enforce_cardinality_constraints(c_inactive_params)

baybe/recommenders/pure/nonpredictive/clustering.py

@@ -107,13 +107,13 @@ def _recommend_discrete(
         from sklearn.preprocessing import StandardScaler
 
         # TODO [Scaling]: scaling should be handled by search space object
+        candidates = subspace_discrete.get_candidates()
+        candidates_comp = subspace_discrete.transform(candidates)
         scaler = StandardScaler()
-        scaler.fit(subspace_discrete.comp_rep)
+        scaler.fit(candidates_comp)
 
         # Scale candidates
-        candidates_scaled = np.ascontiguousarray(
-            scaler.transform(subspace_discrete.comp_rep)
-        )
+        candidates_scaled = np.ascontiguousarray(scaler.transform(candidates_comp))
 
         # Set model parameters and perform fit
         model = self._get_model_cls()(
@@ -129,7 +129,7 @@ def _recommend_discrete(
             selection = self._make_selection_default(model, candidates_scaled)
 
         # Select rows by positional indices and return the corresponding subset
-        return subspace_discrete.exp_rep.iloc[selection]
+        return candidates.iloc[selection]
 
     @override
     def __str__(self) -> str:

baybe/recommenders/pure/nonpredictive/sampling.py

@@ -41,7 +41,7 @@ def _recommend_hybrid(
             if searchspace.type is SearchSpaceType.CONTINUOUS:
                 return cont_random
 
-        candidates_exp = searchspace.discrete.exp_rep
+        candidates_exp = searchspace.discrete.get_candidates()
 
         # Restrict to a random subset if subset-generating constraints are present
         if searchspace.discrete.n_subsets > 0:
@@ -152,11 +152,12 @@ def _recommend_discrete(
         from sklearn.preprocessing import StandardScaler
 
         # TODO [Scaling]: scaling should be handled by search space object
+        candidates = subspace_discrete.get_candidates()
+        candidates_comp = subspace_discrete.transform(candidates)
         scaler = StandardScaler()
-        scaler.fit(subspace_discrete.comp_rep)
+        scaler.fit(candidates_comp)
 
         # Scale and sample
-        candidates_comp = subspace_discrete.comp_rep
         candidates_scaled = np.ascontiguousarray(scaler.transform(candidates_comp))
 
         if active_settings.use_fpsample:
@@ -173,7 +174,7 @@ def _recommend_discrete(
                 initialization=self.initialization.value,
                 random_tie_break=self.random_tie_break,
             )
-        return subspace_discrete.exp_rep.iloc[ilocs]
+        return candidates.iloc[ilocs]
 
     @override
     def __str__(self) -> str:

baybe/searchspace/core.py

@@ -6,7 +6,7 @@
 from collections.abc import Collection, Iterable, Iterator, Sequence
 from enum import Enum
 from itertools import product
-from typing import TYPE_CHECKING, ClassVar, cast
+from typing import TYPE_CHECKING, ClassVar
 
 import numpy as np
 import numpy.typing as npt
@@ -263,7 +263,7 @@ def task_idx(self) -> int | None:
         #       appear first in the computational dataframe.
         #   3.  It assumes there exists exactly one task parameter
         #   --> Fix this when refactoring the data
-        return cast(int, self.discrete.comp_rep.columns.get_loc(task_param.name))
+        return self.discrete.comp_rep_columns.index(task_param.name)
 
     @property
     def n_tasks(self) -> int: