Document how to implement custom models

[HaoLiu56]

Issue description

Provide a short description.

I wonder if we could implement a custom model instead of GP class model.
Specifically, suppose we build a random forest model, and it also have mean and variance for data points. Is it possible to do Bayesian Optimization with this model under BoTorch framework?

Code example

For example:
model = CustomModel(train_X=init_x, train_Y=init_y )

System Info

Please provide information about your setup, including

• BoTorch Version (0.10.0)
• GPyTorch Version (1.11)
• PyTorch Version (2.2.0.post100)
• Computer OS: mac OS Sonoma

[Balandat]

Yes, this is generally possible. BoTorch's Model class only requires you to define a posterior() method that returns a Posterior object, the only requirement of which is to implement an rsample() function for drawing posterior samples (the EnsemblePosterior class provides an implementation for that). Then the MC acquisition function machinery will work with such a setup (EnsemblePosterior also implements mean and variance properties, so some other analytic acquisition functions will also work).

That said, note that in order to use gradient-based optimization of the acquisition function (via the standard optimize_acqf() method) you will need to have the samples drawn from the posterior be differentiable w.r.t. to the input to the posterior() method (this is not the case for Random Forest models). In that case you'll have to perform the acquisition function optimization with gradient-free methods (e.g. CMA-ES or similar methods).

[HaoLiu56]

Great! Could you include some tutorials notebook for this? I'm fairly new to BoTorch.

[jakee417]

@esantorella @Balandat here is an attempt at documenting a custom model that I'd like to submit a PR for: https://github.com/jakee417/botorch/blob/main/tutorials/custom_model.ipynb

One question I have is trying to get MCSampler to work with TorchPosterior. I am getting:

NotImplementedError: A registered `MCSampler` for posterior <botorch.posteriors.torch.TorchPosterior object at 0x1334cf410> is not found. You can implement and register one using `@GetSampler.register`.

But when I try:

from botorch.sampling import get_sampler
from botorch.sampling.base import MCSampler
from botorch.sampling.get_sampler import GetSampler


@GetSampler.register(TorchPosterior)
def _get_sampler_torch(
    posterior: TorchPosterior,
    sample_shape: torch.Size,
    *,
    seed: Optional[int] = None,
) -> MCSampler:
    return get_sampler(
        posterior=posterior,
        sample_shape=sample_shape,
        seed=seed,
    )

it doesn't seem to resolve the issue. Any tips here?

[saitcakmak]

Hi @jakee417. The GetSampler case your register should return a sampler instance rather than calling back get_sampler. If _get_sampler_torch calls get_sampler, you end up in an infinite loop of get_sampler -> GetSampler -> _get_sampler_torch -> get_sampler -> ... calls when there is a TorchPosterior.

[jakee417]

I tried following the example for TransformedPosterior, which I now see is a mistake. But, the infinite loop never even occurred due to the dispatching in _posterior_to_distribution_encoder (had it worked, I do see your point about the cyclic dependency). Instead, referencing the torch.distributions.Distribution seems to catch all of its subclasses:

from botorch.sampling.base import MCSampler
from botorch.sampling.get_sampler import GetSampler
from botorch.sampling.stochastic_samplers import StochasticSampler


@GetSampler.register(distributions.Distribution)
def _get_sampler_torch(
    posterior: TorchPosterior,
    sample_shape: torch.Size,
    *,
    seed: Optional[int] = None,
) -> MCSampler:
    return StochasticSampler(sample_shape=sample_shape, seed=seed)

In this case, the original error:

NotImplementedError: A registered `MCSampler` for posterior <botorch.posteriors.torch.TorchPosterior object at 0x1334cf410> is not found. You can implement and register one using `@GetSampler.register`.

Is a little misleading since you don't need to register botorch.posteriors.torch.TorchPosterior but instead the underlying distribution (again, due to the dispatching).

[saitcakmak]

Ah yes, I forgot that we register them based on the distribution class for TorchPosterior. This is the right way to do it, but ideally we'd register them for the specific distribution class rather than the base class (in case there are custom behaviors for different distributions, like MVN). Left a comment on this on the PR as well. We can continue the discussion there.