Refactor candidates interface

[AdrianSosic]

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.

[Copilot]

Pull request overview

This PR refactors the discrete candidate interface to make SubspaceDiscrete.get_candidates() the single access point for experimental candidates, and shifts computational-representation generation to explicit, on-demand transform(...) calls. This is a preparatory step toward enabling lazy/large-space candidate handling and reducing eager materialization coupling.

Changes:

• Make the experimental representation field private (_exp_rep, aliased as exp_rep for serialization) and deprecate exp_rep/comp_rep accessors in favor of get_candidates() and transform(get_candidates()).
• Simplify SubspaceDiscrete.get_candidates() to return only the experimental representation (pd.DataFrame).
• Update internal call sites, tests, and examples to use the new candidate retrieval + explicit transform flow.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
baybe/searchspace/discrete.py	Privatizes experimental candidates, deprecates legacy accessors, and changes get_candidates() to return only exp-rep.
baybe/searchspace/core.py	Adjusts task column indexing to avoid relying on eager comp_rep.
baybe/campaign.py	Updates candidate filtering/toggling logic to use get_candidates() and evolved discrete subspaces.
baybe/recommenders/pure/base.py	Updates discrete candidate count check to use get_candidates().
baybe/recommenders/naive.py	Switches discrete comp-rep access to on-demand transform(...).
baybe/recommenders/pure/nonpredictive/sampling.py	Updates discrete recommendation flow to fetch candidates via get_candidates() and compute comp-rep via transform(...).
baybe/recommenders/pure/nonpredictive/clustering.py	Same as sampling: comp-rep now computed explicitly from get_candidates().
baybe/recommenders/pure/bayesian/botorch/discrete.py	Replaces eager comp-rep access with transform(get_candidates()) and updates subset evolution.
baybe/recommenders/pure/bayesian/botorch/hybrid.py	Updates hybrid discrete candidate transforms and subset evolution to use get_candidates().
baybe/acquisition/acqfs.py	Updates integration-point generation to explicitly transform candidates on demand.
baybe/simulation/scenarios.py	Updates groupby simulation to build groups from get_candidates().
tests/utils/test_sampling_algorithms.py	Adapts FPS utilities tests to transform candidates explicitly.
tests/utils/test_dataframe.py	Switches fuzzy matching tests to use get_candidates().
tests/test_searchspace.py	Updates discrete searchspace assertions and memory estimate test to use explicit transforms.
tests/test_campaign.py	Updates candidate-related tests to use get_candidates().
tests/test_deprecations.py	Adds coverage for deprecated exp_rep/comp_rep access warnings.
tests/hypothesis_strategies/alternative_creation/test_searchspace.py	Updates hypothesis-based discrete space creation tests to use get_candidates().
tests/constraints/test_constraints_discrete.py	Updates discrete constraint tests to use get_candidates().
tests/constraints/test_cardinality_constraint_discrete.py	Updates cardinality constraint tests to use get_candidates().
examples/Mixtures/slot_based.py	Updates example to use get_candidates() instead of exp_rep.
examples/Custom_Surrogates/custom_pretrained.py	Updates example training data preparation to explicitly transform candidates.
examples/Constraints_Discrete/prodsum_constraints.py	Updates example assertions to use get_candidates().
examples/Constraints_Discrete/exclusion_constraints.py	Updates example assertions to use get_candidates().
examples/Constraints_Discrete/dependency_constraints.py	Updates example assertions to use get_candidates().
examples/Constraints_Discrete/custom_constraints.py	Updates example assertions to use get_candidates().
CHANGELOG.md	Documents breaking API changes and deprecations around candidate accessors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AVHopp]

There is an issue with the computation of the comp_rep_bounds, otherwise LGTM