|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# Copyright (c) Meta Platforms, Inc. and affiliates. |
| 3 | +# |
| 4 | +# This source code is licensed under the MIT license found in the |
| 5 | +# LICENSE file in the root directory of this source tree. |
| 6 | + |
| 7 | +r"""Abstract base module for all botorch acquisition functions.""" |
| 8 | + |
| 9 | +from __future__ import annotations |
| 10 | + |
| 11 | +from abc import ABC, abstractmethod |
| 12 | + |
| 13 | +import torch |
| 14 | + |
| 15 | +from botorch.acquisition import AcquisitionFunction |
| 16 | +from botorch.models.model import Model |
| 17 | +from botorch.utils.transforms import t_batch_mode_transform |
| 18 | +from torch import Tensor |
| 19 | + |
| 20 | + |
| 21 | +class DiscretizedAcquistionFunction(AcquisitionFunction, ABC): |
| 22 | + r"""DiscretizedAcquistionFunction is an abstract base class for acquisition |
| 23 | + functions that are defined on discrete distributions. It wraps a model and |
| 24 | + implements a forward method that computes the acquisition function value at |
| 25 | + a given set of points. |
| 26 | + This class can be subclassed to define acquisiton functions for Riemann- |
| 27 | + distributed posteriors. |
| 28 | + The acquisition function must have the form $$acq(x) = \int p(y|x) ag(x)$$, |
| 29 | + where $$ag$$ is defined differently for each acquisition function. |
| 30 | + The ag_integrate method, which computes the integral of ag between two points, must |
| 31 | + be implemented by subclasses to define the specific acquisition functions. |
| 32 | + """ |
| 33 | + |
| 34 | + def __init__(self, model: Model) -> None: |
| 35 | + r""" |
| 36 | + Initialize the DiscretizedAcquistionFunction |
| 37 | +
|
| 38 | + Args: |
| 39 | + model: A fitted model that is used to compute the posterior |
| 40 | + distribution over the outcomes of interest. |
| 41 | + The model should be a `PFNModel`. |
| 42 | + """ |
| 43 | + |
| 44 | + super().__init__(model=model) |
| 45 | + |
| 46 | + @t_batch_mode_transform(expected_q=1) |
| 47 | + def forward(self, X: Tensor) -> Tensor: |
| 48 | + r"""Evaluate the acquisition function on the candidate set X. |
| 49 | +
|
| 50 | + Args: |
| 51 | + X: A `(b) x q x d`-dim Tensor of `(b)` t-batches with `q` `d`-dim |
| 52 | + design points each. |
| 53 | +
|
| 54 | + Returns: |
| 55 | + A `(b)`-dim Tensor of the acquisition function at the given |
| 56 | + design points `X`. |
| 57 | + """ |
| 58 | + self.to(device=X.device) |
| 59 | + |
| 60 | + discrete_posterior = self.model.posterior(X) |
| 61 | + result = discrete_posterior.integrate(self.ag_integrate) |
| 62 | + # remove q dimension |
| 63 | + return result.squeeze(-1) |
| 64 | + |
| 65 | + @abstractmethod |
| 66 | + def ag_integrate(self, lower_bound: Tensor, upper_bound: Tensor) -> Tensor: |
| 67 | + r""" |
| 68 | + This function calculates the integral that computes the acquisition function |
| 69 | + without the posterior factor from lower_bound to upper_bound. |
| 70 | + That is, our acquisition function is assumed to have the form |
| 71 | + \int ag(x) * p(x) dx, |
| 72 | + and this function calculates \int_{lower_bound}^{upper_bound} ag(x) dx. |
| 73 | + The `integrate` method of the posterior (`BoundedRiemannPosterior`) |
| 74 | + then computes the final acquisition value. |
| 75 | +
|
| 76 | + Args: |
| 77 | + lower_bound: lower bound of integral |
| 78 | + upper_bound: upper bound of integral |
| 79 | +
|
| 80 | + Returns: |
| 81 | + A `(b)`-dim Tensor of acquisition function derivatives at the given |
| 82 | + design points `X`. |
| 83 | + """ |
| 84 | + pass # pragma: no cover |
| 85 | + |
| 86 | + r"""DiscretizedExpectedImprovement is an acquisition function that computes |
| 87 | + the expected improvement over the current best observed value for a Riemann |
| 88 | + distribution.""" |
| 89 | + |
| 90 | + |
| 91 | +class DiscretizedExpectedImprovement(DiscretizedAcquistionFunction): |
| 92 | + r"""DiscretizedExpectedImprovement is an acquisition function that |
| 93 | + computes the expected improvement over the current best observed value |
| 94 | + for a Riemann distribution. |
| 95 | + """ |
| 96 | + |
| 97 | + def __init__(self, model: Model, best_f: Tensor) -> None: |
| 98 | + r""" |
| 99 | + Initialize the DiscretizedExpectedImprovement |
| 100 | +
|
| 101 | + Args: |
| 102 | + model: A fitted model that is used to compute the posterior |
| 103 | + distribution over the outcomes of interest. |
| 104 | + The model should be a `PFNModel`. |
| 105 | + best_f: A tensor representing the current best observed value. |
| 106 | + """ |
| 107 | + super().__init__(model) |
| 108 | + self.register_buffer("best_f", torch.as_tensor(best_f)) |
| 109 | + |
| 110 | + def ag_integrate(self, lower_bound: Tensor, upper_bound: Tensor) -> Tensor: |
| 111 | + r""" |
| 112 | + As Expected improvement has ag(y) = (y - best_f).clamp(min=0), and |
| 113 | + is defined as \int ag(y) * p(y) dy, we can calculate the integral |
| 114 | + of ag(y) like so: |
| 115 | + We just calculate ag(y) at beginning and end, and since the function has |
| 116 | + a gradient of 1 or 0, we can just take the average of the two. |
| 117 | +
|
| 118 | + Args: |
| 119 | + lower_bound: lower bound of integral |
| 120 | + upper_bound: upper bound of integral |
| 121 | +
|
| 122 | + Returns: |
| 123 | + A `(b)`-dim Tensor of acquisition function derivatives at the given |
| 124 | + design points `X`. |
| 125 | + """ |
| 126 | + max_lower_bound_and_f = torch.max(self.best_f, lower_bound) |
| 127 | + bucket_average = (upper_bound + max_lower_bound_and_f) / 2 |
| 128 | + improvement = bucket_average - self.best_f |
| 129 | + |
| 130 | + return improvement.clamp_min(0) |
| 131 | + |
| 132 | + |
| 133 | +class DiscretizedProbabilityOfImprovement(DiscretizedAcquistionFunction): |
| 134 | + r"""DiscretizedProbabilityOfImprovement is an acquisition function that |
| 135 | + computes the probability of improvement over the current best observed value |
| 136 | + for a Riemann distribution. |
| 137 | + """ |
| 138 | + |
| 139 | + def __init__(self, model: Model, best_f: Tensor) -> None: |
| 140 | + r""" |
| 141 | + Initialize the DiscretizedProbabilityOfImprovement |
| 142 | +
|
| 143 | + Args: |
| 144 | + model: A fitted model that is used to compute the posterior |
| 145 | + distribution over the outcomes of interest. |
| 146 | + The model should be a `PFNModel`. |
| 147 | + best_f: A tensor representing the current best observed value. |
| 148 | + """ |
| 149 | + |
| 150 | + super().__init__(model) |
| 151 | + self.register_buffer("best_f", torch.as_tensor(best_f)) |
| 152 | + |
| 153 | + def ag_integrate(self, lower_bound: Tensor, upper_bound: Tensor) -> Tensor: |
| 154 | + r""" |
| 155 | + PI is defined as \int ag(y) * p(y) dy, where ag(y) = I(y - best_f) |
| 156 | + and I being the indicator function. |
| 157 | +
|
| 158 | + So all we need to do is calculate the portion between the bounds |
| 159 | + that is larger than best_f. |
| 160 | + We do this by comparing how much higher the upper bound is than best_f, |
| 161 | + compared to the size of the bucket. |
| 162 | + Then we clamp at one if best_f is below lower_bound and at zero if |
| 163 | + best_f is above upper_bound. |
| 164 | +
|
| 165 | + Args: |
| 166 | + lower_bound: lower bound of integral |
| 167 | + upper_bound: upper bound of integral |
| 168 | +
|
| 169 | + Returns: |
| 170 | + A `(b)`-dim Tensor of acquisition function derivatives at the given |
| 171 | + design points `X`. |
| 172 | + """ |
| 173 | + proportion = (upper_bound - self.best_f) / (upper_bound - lower_bound) |
| 174 | + return proportion.clamp(0, 1) |
0 commit comments