botorch.sampling¶
Monte-Carlo Sampler API¶
The base class for sampler modules to be used with MC-evaluated acquisition functions.
Get Sampler Helper¶
- botorch.sampling.get_sampler.get_sampler(posterior, sample_shape, **kwargs)[source]¶
Get the sampler for the given posterior.
The sampler can be used as sampler(posterior) to produce samples suitable for use in acquisition function optimization via SAA.
- Parameters:
posterior (TorchPosterior) – A Posterior to get the sampler for.
sample_shape (Size) – The sample shape of the samples produced by the given sampler. The full shape of the resulting samples is given by posterior._extended_shape(sample_shape).
kwargs (Any) – Optional kwargs, passed down to the samplers during construction.
- Returns:
The MCSampler object for the given posterior.
- Return type:
MCSampler
List Sampler¶
A SamplerList for sampling from a PosteriorList.
Gaussian Monte-Carlo Samplers¶
Sampler modules producing N(0,1) samples, to be used with MC-evaluated acquisition functions and Gaussian posteriors.
- class botorch.sampling.normal.NormalMCSampler(sample_shape, seed=None, **kwargs)[source]¶
Bases:
MCSampler
,ABC
Base class for samplers producing (possibly QMC) N(0,1) samples.
Subclasses must implement the _construct_base_samples method.
Abstract base class for samplers.
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate. The full shape of the samples is given by posterior._extended_shape(sample_shape).
seed (Optional[int]) – An optional seed to use for sampling.
**kwargs (Any) – Catch-all for deprecated kwargs.
- forward(posterior)[source]¶
Draws MC samples from the posterior.
- Parameters:
posterior (Posterior) – The posterior to sample from.
- Returns:
The samples drawn from the posterior.
- Return type:
Tensor
- training: bool¶
- class botorch.sampling.normal.IIDNormalSampler(sample_shape, seed=None, **kwargs)[source]¶
Bases:
NormalMCSampler
Sampler for MC base samples using iid N(0,1) samples.
Example
>>> sampler = IIDNormalSampler(1000, seed=1234) >>> posterior = model.posterior(test_X) >>> samples = sampler(posterior)
Abstract base class for samplers.
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate. The full shape of the samples is given by posterior._extended_shape(sample_shape).
seed (Optional[int]) – An optional seed to use for sampling.
**kwargs (Any) – Catch-all for deprecated kwargs.
- training: bool¶
- class botorch.sampling.normal.SobolQMCNormalSampler(sample_shape, seed=None, **kwargs)[source]¶
Bases:
NormalMCSampler
Sampler for quasi-MC N(0,1) base samples using Sobol sequences.
Example
>>> sampler = SobolQMCNormalSampler(1024, seed=1234) >>> posterior = model.posterior(test_X) >>> samples = sampler(posterior)
Abstract base class for samplers.
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate. The full shape of the samples is given by posterior._extended_shape(sample_shape).
seed (Optional[int]) – An optional seed to use for sampling.
**kwargs (Any) – Catch-all for deprecated kwargs.
- training: bool¶
Pairwise Monte-Carlo Samplers¶
- class botorch.sampling.pairwise_samplers.PairwiseMCSampler(max_num_comparisons=None, seed=None)[source]¶
Bases:
MCSampler
Abstract class for Pairwise MC Sampler.
This sampler will sample pairwise comparisons. It is to be used together with PairwiseGP and BoTorch acquisition functions (e.g., qKnowledgeGradient)
- Parameters:
max_num_comparisons (int) – Max number of comparisons drawn within samples. If None, use all possible pairwise comparisons
seed (int) – The seed for np.random.seed. If omitted, use a random seed. May be overwritten by sibling classes or subclasses.
- forward(posterior)[source]¶
Draws MC samples from the posterior and make comparisons
- Parameters:
posterior (Posterior) – The Posterior to sample from. The returned samples are expected to have output dimension of 1.
- Returns:
Posterior sample pairwise comparisons.
- Return type:
Tensor
- training: bool¶
- class botorch.sampling.pairwise_samplers.PairwiseIIDNormalSampler(sample_shape, seed=None, max_num_comparisons=None, **kwargs)[source]¶
Bases:
PairwiseMCSampler
,IIDNormalSampler
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate.
seed (Optional[int]) – The seed for the RNG. If omitted, use a random seed.
max_num_comparisons (int) – Max number of comparisons drawn within samples. If None, use all possible pairwise comparisons.
kwargs (Any) – Catch-all for deprecated arguments.
- training: bool¶
- class botorch.sampling.pairwise_samplers.PairwiseSobolQMCNormalSampler(sample_shape, seed=None, max_num_comparisons=None, **kwargs)[source]¶
Bases:
PairwiseMCSampler
,SobolQMCNormalSampler
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate.
seed (Optional[int]) – The seed for the RNG. If omitted, use a random seed.
max_num_comparisons (int) – Max number of comparisons drawn within samples. If None, use all possible pairwise comparisons.
kwargs (Any) – Catch-all for deprecated arguments.
- training: bool¶
QMC Base Functionality¶
Quasi Monte-Carlo sampling from Normal distributions.
References:
- class botorch.sampling.qmc.NormalQMCEngine(d, seed=None, inv_transform=False)[source]¶
Bases:
object
Engine for qMC sampling from a Multivariate Normal N(0, I_d).
By default, this implementation uses Box-Muller transformed Sobol samples following pg. 123 in [Pages2018numprob]. To use the inverse transform instead, set inv_transform=True.
Example
>>> engine = NormalQMCEngine(3) >>> samples = engine.draw(16)
Engine for drawing qMC samples from a multivariate normal N(0, I_d).
- Parameters:
d (int) – The dimension of the samples.
seed (Optional[int]) – The seed with which to seed the random number generator of the underlying SobolEngine.
inv_transform (bool) – If True, use inverse transform instead of Box-Muller.
- draw(n=1, out=None, dtype=torch.float32)[source]¶
Draw n qMC samples from the standard Normal.
- Parameters:
n (int) – The number of samples to draw. As a best practice, use powers of 2.
out (Optional[Tensor]) – An option output tensor. If provided, draws are put into this tensor, and the function returns None.
dtype (dtype) – The desired torch data type (ignored if out is provided).
- Returns:
A n x d tensor of samples if out=None and None otherwise.
- Return type:
Optional[Tensor]
- class botorch.sampling.qmc.MultivariateNormalQMCEngine(mean, cov, seed=None, inv_transform=False)[source]¶
Bases:
object
Engine for qMC sampling from a multivariate Normal N(mu, Sigma).
By default, this implementation uses Box-Muller transformed Sobol samples following pg. 123 in [Pages2018numprob]. To use the inverse transform instead, set inv_transform=True.
Example
>>> mean = torch.tensor([1.0, 2.0]) >>> cov = torch.tensor([[1.0, 0.25], [0.25, 2.0]]) >>> engine = MultivariateNormalQMCEngine(mean, cov) >>> samples = engine.draw(16)
Engine for qMC sampling from a multivariate Normal N(mu, Sigma).
- Parameters:
mean (Tensor) – The mean vector.
cov (Tensor) – The covariance matrix.
seed (Optional[int]) – The seed with which to seed the random number generator of the underlying SobolEngine.
inv_transform (bool) – If True, use inverse transform instead of Box-Muller.
- draw(n=1, out=None)[source]¶
Draw n qMC samples from the multivariate Normal.
- Parameters:
n (int) – The number of samples to draw. As a best practice, use powers of 2.
out (Optional[Tensor]) – An option output tensor. If provided, draws are put into this tensor, and the function returns None.
- Returns:
A n x d tensor of samples if out=None and None otherwise.
- Return type:
Optional[Tensor]
Stochastic Samplers¶
Samplers to enable use cases that are not base sample driven, such as stochastic optimization of acquisition functions.
- class botorch.sampling.stochastic_samplers.ForkedRNGSampler(sample_shape, seed=None, **kwargs)[source]¶
Bases:
MCSampler
A sampler using torch.fork_rng to enable replicable sampling from a posterior that does not support base samples.
NOTE: This approach is not a one-to-one replacement for base sample driven sampling. The main missing piece in this approach is that its outputs are not replicable across the batch dimensions. As a result, when an acquisition function is batch evaluated with repeated candidates, each candidate will produce a different acquisition value, which is not compatible with Sample Average Approximation.
Abstract base class for samplers.
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate. The full shape of the samples is given by posterior._extended_shape(sample_shape).
seed (Optional[int]) – An optional seed to use for sampling.
**kwargs (Any) – Catch-all for deprecated kwargs.
- forward(posterior)[source]¶
Draws MC samples from the posterior in a fork_rng context.
- Parameters:
posterior (Posterior) – The posterior to sample from.
- Returns:
The samples drawn from the posterior.
- Return type:
Tensor
- training: bool¶
- class botorch.sampling.stochastic_samplers.StochasticSampler(sample_shape, seed=None, **kwargs)[source]¶
Bases:
MCSampler
A sampler that simply calls posterior.rsample to generate the samples. This should only be used for stochastic optimization of the acquisition functions, e.g., via gen_candidates_torch. This should not be used with optimize_acqf, which uses deterministic optimizers under the hood.
NOTE: This ignores the seed option.
Abstract base class for samplers.
- Parameters:
sample_shape (torch.Size) – The sample_shape of the samples to generate. The full shape of the samples is given by posterior._extended_shape(sample_shape).
seed (Optional[int]) – An optional seed to use for sampling.
**kwargs (Any) – Catch-all for deprecated kwargs.
- forward(posterior)[source]¶
Draws MC samples from the posterior.
- Parameters:
posterior (Posterior) – The posterior to sample from.
- Returns:
The samples drawn from the posterior.
- Return type:
Tensor
- training: bool¶