Contextual bo generator

[roussel-ryan]

This pull request introduces contextual Bayesian optimization support and improves handling of contextual variables throughout the codebase and documentation. The changes enable users to define contextual variables that are observed (not controlled), ensure correct validation and bounds handling, and provide a new example notebook and documentation entry for contextual Bayesian optimization.

Key changes include:

Contextual Bayesian Optimization Example and Documentation

• Added a new example notebook contextual_bo.ipynb demonstrating and comparing standard versus contextual Bayesian optimization on a drifting objective, and updated the documentation navigation to include this example. [1] [2]

VOCS Validation and Data Handling

• Updated Xopt in xopt/base.py to properly handle contextual variables during input validation: contextual variables are allowed to be missing from candidate data and are filled with NaN for validation purposes. This ensures that contextual variables are treated as observed, not controlled, throughout evaluation and data addition. [1] [2] [3] [4]

Bayesian Generator Improvements

• Refactored the Bayesian generator to support contextual variables:
  • Contextual variables are now imported and handled alongside fixed features.
  • Model input bounds are determined using a new method that accounts for contextual variables.
  • Acquisition functions are now conditioned on the latest observed contextual variable values, and fixed features/contextual variables are applied together in a new unified method.
  • Visualization and optimum finding routines are updated to handle contextual variables appropriately, including special handling for plotting axes and acquisition function display. [1] [2] [3] [4] [5] [6] [7] [8] [9]

These changes collectively enable robust contextual Bayesian optimization workflows and improve clarity and correctness in handling contextual variables across the codebase.

[codecov]

Codecov Report

❌ Patch coverage is 91.98966% with 31 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...pt/tests/generators/bayesian/test_contextual_bo.py	93.10%	7 Missing and 3 partials ⚠️
xopt/vocs.py	82.00%	7 Missing and 2 partials ⚠️
xopt/generators/bayesian/bayesian_generator.py	91.48%	1 Missing and 3 partials ⚠️
xopt/generators/bayesian/turbo.py	76.47%	1 Missing and 3 partials ⚠️
xopt/generators/bayesian/utils.py	77.77%	1 Missing and 1 partial ⚠️
xopt/generators/bayesian/visualize.py	96.00%	0 Missing and 1 partial ⚠️
xopt/tests/test_generator.py	90.90%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[roussel-ryan]

@copilot address the code coverage issues and notebook failures by adding tests and modifying source code / example notebooks as needed

[Copilot]

@copilot address the code coverage issues and notebook failures by adding tests and modifying source code / example notebooks as needed

Addressed the coverage and notebook failures with the following fixes (commits 8cffe9d and 64eac4e):

Notebook failures (multi-fidelity):

• Fixed a variable-ordering bug in convert_numpy_to_inputs (and convert_dataframe_to_inputs) in vocs.py. The PR had changed these to sort variable names alphabetically, but the Bayesian optimizer returns results in vocs.variable_names order. For multi-fidelity this meant the optimizer's x value (≈3.59) was being assigned to s (the fidelity parameter), causing validate_input_data to fail since s must be in [0, 1]. Both functions now preserve vocs.variable_names order, filtering out contextual variables in place.

Bug fix in get_optimum:

• Fixed a TypeError that would occur when contextual_variables is non-empty but fixed_features is None — the code was checking name not in self.fixed_features (which is None). Fixed to use fixed = self.fixed_features or {}.

New tests added:

• test_get_optimum_with_contextual_variable — verifies get_optimum returns only controllable variable candidates
• test_contextual_variable_bounds_from_data — verifies contextual variable bounds are derived from data with 5% padding
• test_contextual_variable — verifies ContextualVariable has infinite domain
• test_convert_numpy_to_inputs_with_contextual_variable — verifies column ordering is preserved and contextual variables are excluded

[Copilot]

Pull request overview

This PR adds first-class support for contextual (observed, not controlled) variables across VOCS handling, Bayesian generator behavior, visualization, and documentation, enabling contextual Bayesian optimization workflows.

Changes:

• Introduces ContextualVariable and updates input conversion/validation paths to allow contextual columns to be omitted from candidates while still validating shapes/bounds.
• Updates Bayesian generators to condition acquisition functions on the latest observed contextual values and to derive contextual input bounds from observed data.
• Adds visualization behavior/tests for contextual axes (acquisition plot replaced by a warning panel), plus a new example notebook and docs nav entry.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
xopt/vocs.py	Adds ContextualVariable and updates dataframe/numpy input conversion to exclude contextual variables.
xopt/base.py	Allows contextual variables to be omitted from candidate inputs by inserting temporary NaN columns for validation.
xopt/generators/bayesian/bayesian_generator.py	Adds contextual conditioning and contextual bounds derivation for model inputs; refactors fixed-feature application.
xopt/generators/bayesian/mobo.py	Routes acquisition post-processing through unified fixed-feature + contextual conditioning helper.
xopt/generators/bayesian/expected_improvement.py	Routes acquisition post-processing through unified fixed-feature + contextual conditioning helper.
xopt/generators/bayesian/visualize.py	Infers finite bounds for contextual variables from data and renders a warning panel when contextual axes are selected for acquisition plots.
xopt/generators/bayesian/bax/visualize.py	Updates mesh generation call to pass data (for contextual-bound inference).
xopt/generators/bayesian/objectives.py	Updates get_sampler import path.
xopt/generators/bayesian/models/standard.py	Adjusts optimizer selection/options to improve compatibility across batched models / botorch+scipy variants.
xopt/tests/test_vocs.py	Adds tests for ContextualVariable and numpy-to-input conversion with contextual vars/order preservation.
xopt/tests/generators/bayesian/test_visualize.py	Adds tests for acquisition plotting/visualization warnings when contextual axes are selected.
xopt/tests/generators/bayesian/test_model_constructor.py	Makes training comparison test less optimizer-callback dependent and relaxes hyperparameter matching tolerance.
xopt/tests/generators/bayesian/test_contextual_bo.py	New end-to-end tests covering contextual BO generation, bounds, and visualization warnings.
mkdocs.yml	Adds the contextual BO example notebook to documentation navigation.
docs/examples/single_objective_bayes_opt/contextual_bo.ipynb	New example notebook demonstrating standard vs contextual BO on a drifting objective.

---

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

[nikitakuklev]

did you mean to commit this?

[roussel-ryan]

nope! removed

[nikitakuklev]

Overall I don't have strong opinion on adding a special contextual variables type, but the current implementation is problematic.

Changing get_variable_bounds to drop entries breaks the implicit "one entry per variable, in variable_names order" contract relied upon everywhere (and in apsopt). I strongly suggest reverting that and instead handling exclusions at call site. This will resolve some bugs I commented on.

Other stuff:

• AsynchronousXopt might have issues (haven't checked).
• Serialization seems broken (haven't checked) because of how gest-api resolves types with only its own. Contextual variables need to be monkeypatched into gest-api/globals() before attempting to load, or we upstream some registry system.

[nikitakuklev]

This is a problem for methods like _get_optimization_bounds if contextual variable is declared first. For example, using {"c": ContextualVariable(), "x": [0,1]} will crash on step()

[nikitakuklev]

So you need to compute indices against the same reduced list

[nikitakuklev]

if this value is nan, bad things happen because acq is poisoned (like effectively random sampling)

[roussel-ryan]

Thanks for the comments @nikitakuklev I will look them over and modify the implementation

[roussel-ryan]

Previously I implemented a contextual variable as a subclass of continuous variable, with a domain of [-inf,inf], do you think that would work better?

[nikitakuklev]

Taking a step back, what is the motivation for adding a dedicated contextual variable class? To my understanding, in current definition a contextual variable is a fixed feature whose value is resolved at acquisition time from the latest observation instead of being a constant or set by user externally (for example, by the script manually reading the context just before step like we do in practice).

So, one option is to just add contextual_variables: list[str] to BayesianGenerator(...), which does cause some overlap with fixed_features but has advantage of very low impact on anything else, reusing almost all existing code.

If you want a ContextualVariable as proper class to make it very explicit to users, then yes, we should subclass ContinuousVariable but require user to set an explicit limit for what is considered sane. Then everything mostly works as is. Alternatively use -inf/inf as indicators to infer bounds from data - a bit more work, but nice flexibility. We would still need to monkeypatch gest-api for serialization round-trip to work (need to test this).

Regardless of method, also need supports_contextual_variables flag on all generators

[roussel-ryan]

Thanks for the comments @nikitakuklev. My original implementation added contextual variables as a property of the BayesianGenerator class, but then I felt it made more sense to promote it to a full class to make it more explicit (+ also make it more natural to check that the correct data exists / do visualization of the model). I think we can go the route of defaulting the domain to [-inf, inf] and then at runtime infer the domain with some documentation to make this clear to the user. I will work on this and then ping you again when it is ready.