# botorch.sampling¶

## botorch.sampling.qmc¶

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.

### NormalQMCEngine¶

class botorch.sampling.qmc.NormalQMCEngine(d, seed=None, inv_transform=False)[source]

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(10)


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.

• 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).

Return type

Optional[Tensor]

Returns

A n x d tensor of samples if out=None and None otherwise.

### MultivariateNormalQMCEngine¶

class botorch.sampling.qmc.MultivariateNormalQMCEngine(mean, cov, seed=None, inv_transform=False)[source]

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(10)


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.

• out (Optional[Tensor]) – An option output tensor. If provided, draws are put into this tensor, and the function returns None.

Return type

Optional[Tensor]

Returns

A n x d tensor of samples if out=None and None otherwise.

## botorch.sampling.samplers¶

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

### MCSampler¶

class botorch.sampling.samplers.MCSampler[source]

Abstract base class for Samplers.

Subclasses must implement the _construct_base_samples method.

sample_shape

The shape of each sample.

resample

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).

collapse_batch_dims

If True, collapse the t-batch dimensions of the produced samples to size 1. This is useful for preventing sampling variance across t-batches.

Example

This method is usually not called directly, but via the sampler’s __call__ method: >>> posterior = model.posterior(test_X) >>> samples = sampler(posterior)

forward(posterior)[source]

Draws MC samples from the posterior.

Parameters

posterior (Posterior) – The Posterior to sample from.

Return type

Tensor

Returns

The samples drawn from the posterior.

property sample_shape

The shape of a single sample

Return type

Size

### IIDNormalSampler¶

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

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.

### SobolQMCNormalSampler¶

class botorch.sampling.samplers.SobolQMCNormalSampler(num_samples, resample=False, seed=None, collapse_batch_dims=True)[source]

Sampler for quasi-MC base samples using Sobol sequences.

Example

>>> sampler = SobolQMCNormalSampler(1000, 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.

• 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.