Sampling

Sampling methods are provided by the QuasiMonteCarlo package. The SamplingAlgorithm interface and the GridSample, RandomSample, SobolSample, LatinHypercubeSample, HaltonSample, KroneckerSample, and GoldenSample types are defined and documented there. Surrogates.jl re-exports these names so they can be used directly with sample.

Surrogates.sample — Function

sample(n, lb, ub, sampler::SamplingAlgorithm; kwargs...)

Generate sample points for a surrogate model using a QuasiMonteCarlo sampling algorithm. Surrogates.jl wraps QuasiMonteCarlo.sample and converts its matrix output to the historical Surrogates.jl representation: a vector for one-dimensional samples and a vector of tuples for multidimensional samples.

Arguments

n::Integer: Number of sample points to generate.
lb: Lower bound for the sampled domain. Use a number for one-dimensional domains or a vector/tuple for multidimensional domains.
ub: Upper bound for the sampled domain. It must have the same dimensionality as lb.
sampler::SamplingAlgorithm: Sampling strategy such as SobolSample(), RandomSample(), or HaltonSample().

Keywords

kwargs...: Additional keyword arguments forwarded to QuasiMonteCarlo.sample.

Returns

For one-dimensional bounds, a vector of sampled values.
For multidimensional bounds, a vector of tuples whose entries are sample coordinates.

Examples

using Surrogates

x = sample(5, 0.0, 1.0, SobolSample())
xy = sample(5, [0.0, 0.0], [1.0, 1.0], SobolSample())

source

sample(n,lb,ub,K::SectionSample)

Returns Tuples constrained to a section. In surrogate-based identification and control, optimization can alternate between unconstrained sampling in the full-dimensional parameter space, and sampling constrained on specific sections (e.g. a planes in a 3D volume), A SectionSample allows sampling and optimizing on a subset of 'free' dimensions while keeping 'fixed' ones constrained. The sampler is defined as in e.g. section_sampler_y_is_10 = SectionSample([NaN64, NaN64, 10.0, 10.0], UniformSample()) where the first argument is a Vector{T} in which numbers are fixed coordinates and NaNs correspond to free dimensions, and the second argument is a SamplingAlgorithm which is used to sample in the free dimensions.

source

SectionSample(n, d, K::SectionSample)

In surrogate-based identification and control, optimization can alternate between unconstrained sampling in the full-dimensional parameter space, and sampling constrained on specific sections (e.g. planes in a 3D volume). SectionSample allows sampling and optimizing on a subset of 'free' dimensions while keeping 'fixed' ones constrained. The sampler is defined SectionSample([NaN64, NaN64, 10.0, 10.0], UniformSample()) where the first argument is a Vector{T} in which numbers are fixed coordinates and NaNs correspond to free dimensions, and the second argument is a SamplingAlgorithm which is used to sample in the free dimensions.

source

Surrogates.SectionSample — Type

SectionSample(x0::AbstractVector, sampler::SamplingAlgorithm)

Sampling algorithm that keeps selected dimensions fixed while sampling the remaining dimensions. In x0, entries equal to NaN are free dimensions, and numeric entries are fixed coordinates.

Arguments

x0::AbstractVector: Section definition. Use NaN for coordinates that should be sampled and finite numbers for coordinates that should remain fixed.
sampler::SamplingAlgorithm: Sampling strategy to use on the free dimensions.

Fields

x0: Section definition supplied to the constructor.
sa: Sampling algorithm used for the free dimensions.
fixed_dims: Indices cached by the constructor for sample(n, section). For the default constructor, these are the coordinates where x0 is NaN.

Examples

using Surrogates

section = SectionSample([NaN, 0.5], SobolSample())
sample(4, [0.0, 0.0], [1.0, 1.0], section)

source

The syntax for sampling in an interval or region is the following:

sample(n, lb, ub, S::SamplingAlgorithm)

where lb and ub are, respectively, the lower and upper bounds. There are many sampling algorithms to choose from:

Grid sample

sample(n, lb, ub, GridSample())

Uniform sample

sample(n, lb, ub, RandomSample())

Sobol sample

sample(n, lb, ub, SobolSample())

Latin Hypercube sample

sample(n, lb, ub, LatinHypercubeSample())

Low Discrepancy sample

sample(n, lb, ub, HaltonSample())

Sample on section

sample(n, lb, ub, SectionSample())

Adding a new sampling method

Adding a new sampling method is a two-step process:

Adding a new SamplingAlgorithm type
Overloading the sample function with the new type.

Example

struct NewAmazingSamplingAlgorithm{OPTIONAL} <: QuasiMonteCarlo.SamplingAlgorithm end

function sample(n, lb, ub, ::NewAmazingSamplingAlgorithm)
    if lb isa Number
        ...
        return x
    else
        ...
        return Tuple.(x)
    end
end