Deprecate gp_sampling module in favor of pathwise sampling (#2432)

Summary:
Pull Request resolved: #2432

GP sampling functionality has been superseded by pathwise sampling, which has been in BoTorch for quite some time now. Marking it for deprecation in v0.13.

All existing usage has been replaced with `get_matheron_path_model`.

Differential Revision: D59815658

botorch/acquisition/multi_objective/utils.py

@@ -27,7 +27,7 @@
 from botorch.models.fully_bayesian import MCMC_DIM
 from botorch.models.model import Model
 from botorch.sampling.get_sampler import get_sampler
-from botorch.utils.gp_sampling import get_gp_samples
+from botorch.sampling.pathwise.posterior_samplers import get_matheron_path_model
 from botorch.utils.multi_objective.box_decompositions.box_decomposition import (
     BoxDecomposition,
 )
@@ -320,7 +320,6 @@ def sample_optimal_points(
     optimizer: Callable[
         [GenericDeterministicModel, Tensor, int, bool, Any], Tuple[Tensor, Tensor]
     ] = random_search_optimizer,
-    num_rff_features: int = 512,
     maximize: bool = True,
     optimizer_kwargs: Optional[Dict[str, Any]] = None,
 ) -> Tuple[Tensor, Tensor]:
@@ -344,7 +343,6 @@ def sample_optimal_points(
         num_samples: The number of GP samples.
         num_points: The number of optimal points to be outputted.
         optimizer: A callable that solves the deterministic optimization problem.
-        num_rff_features: The number of random Fourier features.
         maximize: If true, we consider a maximization problem.
         optimizer_kwargs: The additional arguments for the optimizer.
 
@@ -356,7 +354,7 @@ def sample_optimal_points(
         - A `num_samples x num_points x M`-dim Tensor containing the collection of
             optimal objectives.
     """
-    tkwargs = {"dtype": bounds.dtype, "device": bounds.device}
+    tkwargs: Dict[str, Any] = {"dtype": bounds.dtype, "device": bounds.device}
     M = model.num_outputs
     d = bounds.shape[-1]
     if M == 1:
@@ -369,9 +367,7 @@ def sample_optimal_points(
     pareto_sets = torch.zeros((num_samples, num_points, d), **tkwargs)
     pareto_fronts = torch.zeros((num_samples, num_points, M), **tkwargs)
     for i in range(num_samples):
-        sample_i = get_gp_samples(
-            model=model, num_outputs=M, n_samples=1, num_rff_features=num_rff_features
-        )
+        sample_i = get_matheron_path_model(model=model)
         ps_i, pf_i = optimizer(
             model=sample_i,
             bounds=bounds,

botorch/models/deterministic.py

@@ -19,8 +19,8 @@
 observation. `GenericDeterministicModel` supports arbitrary deterministic
 functions, while `AffineFidelityCostModel` is a particular cost model for
 multi-fidelity optimization. Other use cases of deterministic models include
-representing approximate GP sample paths, e.g. random Fourier features obtained
-with `get_gp_samples`, which allows them to be substituted in acquisition
+representing approximate GP sample paths, e.g. Matheron paths obtained
+with `get_matheron_path_model`, which allows them to be substituted in acquisition
 functions or in other places where a `Model` is expected.
 """
 

botorch/utils/gp_sampling.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import warnings
 from copy import deepcopy
 from math import pi
 from typing import List, Optional
@@ -41,6 +42,14 @@ def __init__(self, model: Model, seed: Optional[int] = None) -> None:
         Args:
             model: The Model defining the GP prior.
         """
+        warnings.warn(
+            "`GPDraw` is deprecated and will be removed in v0.13 release. "
+            "For drawing GP sample paths, we recommend using pathwise "
+            "sampling code found in `botorch/sampling/pathwise`. We recommend "
+            "`get_matheron_path_model` for most use cases.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__()
         self._model = deepcopy(model)
         self._num_outputs = self._model.num_outputs
@@ -429,6 +438,14 @@ def get_gp_samples(
         A `GenericDeterministicModel` that evaluates `n_samples` sampled functions.
         If `n_samples > 1`, this will be a batched model.
     """
+    warnings.warn(
+        "`get_gp_samples` is deprecated and will be removed in v0.13 release. "
+        "For drawing GP sample paths, we recommend using pathwise "
+        "sampling code found in `botorch/sampling/pathwise`. We recommend "
+        "`get_matheron_path_model` for most use cases.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     # Get transforms from the model.
     intf = getattr(model, "input_transform", None)
     octf = getattr(model, "outcome_transform", None)

test/acquisition/multi_objective/test_utils.py

@@ -24,7 +24,7 @@
 from botorch.models.gp_regression import SingleTaskGP
 from botorch.models.model_list_gp_regression import ModelListGP
 from botorch.models.transforms.outcome import Standardize
-from botorch.utils.gp_sampling import get_gp_samples
+from botorch.sampling.pathwise import get_matheron_path_model
 from botorch.utils.multi_objective import is_non_dominated
 from botorch.utils.testing import BotorchTestCase, MockModel, MockPosterior
 from torch import Tensor
@@ -306,11 +306,7 @@ def test_random_search_optimizer(self):
                 **tkwargs,
             )
 
-            model_sample = get_gp_samples(
-                model=model,
-                num_outputs=num_objectives,
-                n_samples=1,
-            )
+            model_sample = get_matheron_path_model(model=model)
 
             input_dim = X.shape[-1]
             # fake bounds

test/utils/test_gp_sampling.py

@@ -190,7 +190,10 @@ def test_gp_draw_single_output(self):
             tkwargs = {"device": self.device, "dtype": dtype}
             model, _, _ = _get_model(**tkwargs)
             mean = model.mean_module.raw_constant.detach().clone()
-            gp = GPDraw(model)
+            with self.assertWarnsRegex(
+                DeprecationWarning, "is deprecated and will be removed"
+            ):
+                gp = GPDraw(model)
             # test initialization
             self.assertIsNone(gp.Xs)
             self.assertIsNone(gp.Ys)
@@ -547,16 +550,19 @@ def test_get_gp_samples(self):
                 )
                 with torch.random.fork_rng():
                     torch.manual_seed(0)
-                    gp_samples = get_gp_samples(
-                        model=(
-                            batched_to_model_list(model)
-                            if ((not use_batch_model) and (m > 1))
-                            else model
-                        ),
-                        num_outputs=m,
-                        n_samples=n_samples,
-                        num_rff_features=512,
-                    )
+                    with self.assertWarnsRegex(
+                        DeprecationWarning, "is deprecated and will be removed"
+                    ):
+                        gp_samples = get_gp_samples(
+                            model=(
+                                batched_to_model_list(model)
+                                if ((not use_batch_model) and (m > 1))
+                                else model
+                            ),
+                            num_outputs=m,
+                            n_samples=n_samples,
+                            num_rff_features=512,
+                        )
                 samples = gp_samples.posterior(X).mean
                 self.assertEqual(samples.shape[0], n_samples)
                 if batched_inputs: