Surrogates User Guide by AdrianSosic · Pull Request #801 · emdgroup/baybe

AdrianSosic · 2026-05-20T13:24:43Z

DevPR, parent is #745

Updates the surrogate user guide to mention all the newly added features.

Rendered doc on fork: https://adriansosic.github.io/baybe-dev/latest/userguide/surrogates.html

Copilot

Pull request overview

Updates BayBE’s surrogate documentation and accompanying code/tests to reflect newly added Gaussian process (GP) configurability and presets, including a BoTorch-aligned preset and supporting multitask/transfer-learning utilities.

Changes:

Expanded the Surrogates user guide with a detailed GP section (components, customization, presets, alternatives, custom surrogates).
Added a new BOTORCH GP preset plus supporting GPyTorch helpers and kernel-factory validation.
Updated tests, Streamlit demo, and warnings configuration to accommodate the new GP components/preset behavior.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`tests/test_kernels.py`	Adjusts kernel evaluation to use dense conversion (`to_dense`) for loss computation.
`tests/test_imports.py`	Ensures the new `_gpytorch` components module is import-tested under torch deps.
`tests/test_gp.py`	Adds a BoTorch-preset equivalence test (single- and multi-task) and updates criterion naming.
`streamlit/surrogate_models.py`	Extends the Streamlit demo with multitask + transfer learning controls and GP preset selection.
`pytest.ini`	Filters a known `linear_operator` warning.
`docs/userguide/surrogates.md`	Major rewrite/expansion of surrogate documentation, focusing on GP usage and presets.
`docs/conf.py`	Adds GPyTorch intersphinx mapping for external API linking.
`CHANGELOG.md`	Mentions the new `BOTORCH` GP preset in the “Added” section.
`baybe/surrogates/gaussian_process/presets/core.py`	Introduces `GaussianProcessPreset.BOTORCH`.
`baybe/surrogates/gaussian_process/presets/botorch.py`	Implements kernel/mean/likelihood/fit-criterion factories intended to mimic BoTorch defaults.
`baybe/surrogates/gaussian_process/presets/__init__.py`	Exposes the BoTorch preset factories in the presets package exports.
`baybe/surrogates/gaussian_process/core.py`	Renames fit-criterion factory plumbing and updates preset construction behavior.
`baybe/surrogates/gaussian_process/components/kernel.py`	Updates factory typing and strengthens multitask kernel active-dimension validation.
`baybe/surrogates/gaussian_process/components/_gpytorch.py`	Adds custom GPyTorch mean + multitask likelihood helpers used by the BoTorch preset.

Comments suppressed due to low confidence (1)

baybe/surrogates/gaussian_process/core.py:193

GaussianProcessSurrogate previously accepted criterion_or_factory (and exposed criterion_factory). Renaming the init alias to fit_criterion_or_factory is a breaking API change without a compatibility path. Consider supporting both names (with a deprecation warning for the old one) and/or documenting it under ### Breaking Changes in the changelog.

    fit_criterion_factory: FitCriterionFactoryProtocol = field(
        alias="fit_criterion_or_factory",
        factory=BayBEFitCriterionFactory,
        converter=partial(  # type: ignore[misc]
            to_component_factory, component_type=GPComponentType.CRITERION
        ),
        validator=is_callable(),
    )

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

AdrianSosic · 2026-05-20T19:20:25Z

@copilot: The PR has now been rebased. Please close all thread from your current review and start a fresh one.

Copilot · 2026-05-20T19:21:35Z

@copilot: The PR has now been rebased. Please close all thread from your current review and start a fresh one.

I can’t close or reopen GitHub review threads from this coding-agent interface. No code changes were required for this request on branch docs/surrogates (current head: 80e4d9d). If you want, I can proceed with a fresh pass over the rebased diff and address any new review findings.

Copilot

Pull request overview

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

+user-friendly as possible, BayBE allows you to specify each of these components in
+multiple ways:
+* As a BayBE object representing the component (e.g., a
+  {class}`~baybe.kernels.base.Kernel` object)
+* As a low-level [GPyTorch](https://gpytorch.ai/) component (e.g., a
+  {class}`gpytorch.kernels.Kernel`)
+* Or most flexibly: as a *factory* producing either of the two above.
+  More precisely: a callable that receives the actual recommendation context and
+  dynamically returns a component produced specifically for the problem at hand. 
+


+cost becomes a major concern. For these cases, BayBE offers a range of alternative
+surrogate models:


Scienfitz

very well written 👏

Scienfitz · 2026-05-22T16:31:39Z

+
+| Component | Role |
+|-----------|------|
+| **Kernel** | Encodes assumptions about the function's structure. |


my personal preference: remove the dots int he end of sentences in such small bulletpoint-like notes
(feel free to ignore)

Suggested change

| **Kernel** | Encodes assumptions about the function's structure. |

| **Kernel** | Encodes assumptions about the function's structure |

Scienfitz · 2026-05-22T16:32:13Z

+Configuring these components in the right way is key to unlocking the full potential of
+the Bayesian optimization process since they directly drive the surrogate's predictions
+and thus its ability to describe your data. Therefore, we invest much effort into
+making BayBE's *default GP configuration* a solid, well-tested choice for a wide range


italic usage here feels strange to me

Scienfitz · 2026-05-22T16:32:56Z

+multiple ways:
+* As a BayBE object representing the component (e.g., a
+  {class}`~baybe.kernels.base.Kernel` object)
+* As a low-level [GPyTorch](https://gpytorch.ai/) component (e.g., a


needs an admonition warning that this would break serializaiton

Scienfitz · 2026-05-22T16:34:11Z

+| **Kernel** | Encodes assumptions about the function's structure. |
+| **Mean function** | The expected function values prior to observing any data. |
+| **Likelihood** | Encodes assumptions about the observation noise. |
+| **Fit criterion** | The optimization objective used to tune the model hyperparameters. |


seeing a 5th component here called Observation-Standardization would make everyone feel like

Scienfitz · 2026-05-22T16:36:24Z

+  {class}`gpytorch.kernels.Kernel`)
+* Or most flexibly: as a *factory* producing either of the two above.
+  More precisely: a callable that receives the actual recommendation context and
+  dynamically returns a component produced specifically for the problem at hand. 


should we link athh the relevant factory protocols so users can immediatley find the reuqired signatures?

Scienfitz · 2026-05-22T16:40:17Z

+    outputscale_initial_value=2.0,
+)
+
+# Restricting a kernel to specific parameters


this deserves more attention, how about a separate snippet that tells how to leave the overall kernel untouched and just change the kernel for 1 parameter?

ah I realize thats prob not yet possible or at least not possible in the "nice" way of doing that directly in the parameter configuraiton... but that would be the place here to show it, right?

AdrianSosic added this to the 0.15.0 milestone May 20, 2026

AdrianSosic self-assigned this May 20, 2026

AdrianSosic added the documentation Improvements or additions to documentation label May 20, 2026

AdrianSosic changed the base branch from main to dev/gp May 20, 2026 13:24

AdrianSosic force-pushed the docs/surrogates branch from f2e1448 to eb988ba Compare May 20, 2026 13:46

AdrianSosic marked this pull request as ready for review May 20, 2026 13:46

AdrianSosic requested review from AVHopp and Scienfitz as code owners May 20, 2026 13:46

Copilot AI review requested due to automatic review settings May 20, 2026 13:46

Copilot started reviewing on behalf of AdrianSosic May 20, 2026 13:47 View session

Copilot AI reviewed May 20, 2026

View reviewed changes

Draft new surrogate user guide

80e4d9d

AdrianSosic force-pushed the docs/surrogates branch from eb988ba to 80e4d9d Compare May 20, 2026 18:53

Copilot started work on behalf of AdrianSosic May 20, 2026 19:20 View session

Copilot finished work on behalf of AdrianSosic May 20, 2026 19:21

AdrianSosic requested a review from Copilot May 20, 2026 19:26

Copilot started reviewing on behalf of AdrianSosic May 20, 2026 19:27 View session

Copilot AI reviewed May 20, 2026

View reviewed changes

AdrianSosic added 2 commits May 20, 2026 21:35

Ignore NumericalWarning about negative variances in test suite

d0468bd

Fix import path in code snippet

7d23b1b

Scienfitz approved these changes May 22, 2026

View reviewed changes

		cost becomes a major concern. For these cases, BayBE offers a range of alternative
		surrogate models:

	\| Kernel \| Encodes assumptions about the function's structure. \|
	\| Kernel \| Encodes assumptions about the function's structure \|

Conversation

AdrianSosic commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AdrianSosic commented May 20, 2026

Uh oh!

Copilot AI commented May 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Scienfitz left a comment

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Scienfitz May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AdrianSosic commented May 20, 2026 •

edited

Loading