botorch.sampling

Monte-Carlo Samplers

Sampler modules to be used with MC-evaluated acquisition functions.

class botorch.sampling.samplers.IIDNormalSampler(num_samples, resample=False, seed=None, collapse_batch_dims=True, batch_range=(0, -2))[source]

Bases: MCSampler

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)

Sampler for MC base samples using iid N(0,1) samples.

Parameters:
  • num_samples (int) – The number of samples to use.

  • resample (bool) – If True, re-draw samples in each forward evaluation - this results in stochastic acquisition functions (and thus should not be used with deterministic optimization algorithms).

  • seed (Optional[int]) – The seed for the RNG. If omitted, use a random seed.

  • collapse_batch_dims (bool) – If True, collapse the t-batch dimensions to size 1. This is useful for preventing sampling variance across t-batches.

  • batch_range (Tuple[int, int]) – The range of t-batch dimensions in the base_sample_shape used by collapse_batch_dims. The t-batch dims are batch_range[0]:batch_range[1]. By default, this is (0, -2), for the case where the non-batch dimensions are -2 (q) and -1 (d) and all dims in the front are t-batch dims.

training: bool
class botorch.sampling.samplers.SobolQMCNormalSampler(num_samples, resample=False, seed=None, collapse_batch_dims=True, batch_range=(0, -2))[source]

Bases: MCSampler

Sampler for quasi-MC base samples using Sobol sequences.

Example

>>> sampler = SobolQMCNormalSampler(1024, seed=1234)
>>> posterior = model.posterior(test_X)
>>> samples = sampler(posterior)

Sampler for quasi-MC base samples using Sobol sequences.

Parameters:
  • num_samples (int) – The number of samples to use. As a best practice, use powers of 2.

  • resample (bool) – If True, re-draw samples in each forward evaluation - this results in stochastic acquisition functions (and thus should not be used with deterministic optimization algorithms).

  • seed (Optional[int]) – The seed for the RNG. If omitted, use a random seed.

  • collapse_batch_dims (bool) – If True, collapse the t-batch dimensions to size 1. This is useful for preventing sampling variance across t-batches.

  • batch_range (Tuple[int, int]) – The range of t-batch dimensions in the base_sample_shape used by collapse_batch_dims. The t-batch dims are batch_range[0]:batch_range[1]. By default, this is (0, -2), for the case where the non-batch dimensions are -2 (q) and -1 (d) and all dims in the front are t-batch dims.

training: bool
botorch.sampling.samplers.split_shapes(base_sample_shape)[source]

Split a base sample shape into sample and base sample shapes.

Parameters:

base_sample_shape (Size) – The base sample shape.

Returns:

A tuple containing the sample and base sample shape.

Return type:

Tuple[Size, Size]

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(num_samples, resample=False, seed=None, collapse_batch_dims=True, max_num_comparisons=None)[source]

Bases: PairwiseMCSampler, IIDNormalSampler

Parameters:
  • num_samples (int) – The number of samples to use.

  • resample (bool) – If True, re-draw samples in each forward evaluation - this results in stochastic acquisition functions (and thus should not be used with deterministic optimization algorithms).

  • seed (Optional[int]) – The seed for the RNG. If omitted, use a random seed.

  • collapse_batch_dims (bool) – If True, collapse the t-batch dimensions to size 1. This is useful for preventing sampling variance across t-batches.

  • max_num_comparisons (int) – Max number of comparisons drawn within samples. If None, use all possible pairwise comparisons.

training: bool
class botorch.sampling.pairwise_samplers.PairwiseSobolQMCNormalSampler(num_samples, resample=False, seed=None, collapse_batch_dims=True, max_num_comparisons=None)[source]

Bases: PairwiseMCSampler, SobolQMCNormalSampler

Parameters:
  • num_samples (int) – The number of samples to use.

  • resample (bool) – If True, re-draw samples in each forward evaluation - this results in stochastic acquisition functions (and thus should not be used with deterministic optimization algorithms).

  • seed (Optional[int]) – The seed for the RNG. If omitted, use a random seed.

  • collapse_batch_dims (bool) – If True, collapse the t-batch dimensions to size 1. This is useful for preventing sampling variance across t-batches.

  • max_num_comparisons (int) – Max number of comparisons drawn within samples. If None, use all possible pairwise comparisons.

training: bool

QMC Base Functionality

Quasi Monte-Carlo sampling from Normal distributions.

References:

[Pages2018numprob] (1,2)

G. Pages. Numerical Probability: An Introduction with Applications to Finance. Universitext. Springer International Publishing, 2018.

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]