Developer API

The interfaces on this page are public and versioned for package developers building integrations with QuasiMonteCarlo.jl. They are not exported and are not intended as the ordinary user-facing sampling API. Use sample for application code.

Sequence validation

The shared sequence validator lets downstream sampler implementations apply the same bounds and sample-count requirements as QuasiMonteCarlo.jl.

QuasiMonteCarlo._check_sequence — Function

_check_sequence(n::Integer)
_check_sequence(lb, ub, n::Integer)

Validate the sample count and, when supplied, the bounds of a sampling sequence.

Arguments

n: Number of sample points. It must be greater than zero.
lb: Lower bounds. It must have the same length as ub, and every lower bound must be less than or equal to the corresponding upper bound.
ub: Upper bounds. It must have the same length as lb.

Returns

nothing: Returned when all validations pass.

Throws

AssertionError: Thrown when n is not positive, when lb and ub have different lengths, or when any lower bound exceeds its corresponding upper bound.

Examples

julia> using QuasiMonteCarlo

julia> QuasiMonteCarlo._check_sequence(8)

julia> QuasiMonteCarlo._check_sequence([0.0, -1.0], [1.0, 1.0], 8)

julia> QuasiMonteCarlo._check_sequence([0.0, 2.0], [1.0, 1.0], 8)
ERROR: AssertionError: Lower bound exceeds upper bound (lb > ub)

source

Extension interfaces

The following interfaces are public for package developers. They describe the minimum contracts used by the generic sampling and design-matrix functions. They are not exported, so application code should use the exported sample, randomize, DesignMatrix, and generate_design_matrices functions instead of calling implementation hooks directly.

QuasiMonteCarlo.RandomSamplingAlgorithm — Type

RandomSamplingAlgorithm <: SamplingAlgorithm

Abstract interface for samplers that generate randomized point sets.

Subtypes must implement the unit-box method sample(n::Integer, d::Integer, sampler, T = Float64) described by SamplingAlgorithm. The implementation must use the sampler's randomness, return a d-by-n matrix with entries in [0, 1], and preserve the requested element type when T is supplied.

The generate_design_matrices interface treats each call to sample as an independent realization. A sampler should therefore store its random state in a field, such as the rng field on RandomSample, and should not cache a point set between calls unless that behavior is part of its contract.

This type is a developer-facing interface and is not exported. Refer to it as QuasiMonteCarlo.RandomSamplingAlgorithm when defining an extension.

source

QuasiMonteCarlo.DeterministicSamplingAlgorithm — Type

DeterministicSamplingAlgorithm <: SamplingAlgorithm

Abstract interface for deterministic low-discrepancy samplers.

Subtypes must implement the unit-box method sample(n::Integer, d::Integer, sampler, T = Float64) described by SamplingAlgorithm. The underlying sequence must be deterministic for equivalent sampler state; a non-NoRandR field may intentionally add randomization to the returned point set. The result must be a d-by-n matrix with entries in [0, 1] and element type T when T is supplied.

To use the generic DesignMatrix or generate_design_matrices interfaces, a concrete subtype must also provide an R::RandomizationMethod field. That field supplies the default randomization method. A custom randomization method must follow the RandomizationMethod contract.

This type is a developer-facing interface and is not exported. Refer to it as QuasiMonteCarlo.DeterministicSamplingAlgorithm when defining an extension.

source

QuasiMonteCarlo.AbstractDesignMatrix — Type

AbstractDesignMatrix

Developer-facing interface for iterators returned by DesignMatrix.

Concrete subtypes must store a count field and implement next!(iterator), which produces the next point-set matrix. The generic Base.length and Base.iterate methods use those two pieces of the contract: iteration yields exactly count matrices, and each call to next! may reuse internal storage but must return a complete matrix before the next iteration step mutates that storage.

Implementations should also define Base.eltype(::Type{<:AbstractDesignMatrix}) to describe the matrix type yielded by iteration. This interface is intended for package developers extending the design-matrix machinery; application code should call DesignMatrix and iterate over its result.

source

Generic contract example

An extension only needs to implement the unit-box sample method. The bounds and design-matrix methods are supplied by QuasiMonteCarlo.jl:

struct CenterSampler <: QuasiMonteCarlo.SamplingAlgorithm end

function QuasiMonteCarlo.sample(n::Integer, d::Integer,
        ::CenterSampler, T = Float64)
    return fill(convert(T, 0.5), d, n)
end

points = QuasiMonteCarlo.sample(4, [-1.0, 2.0], [1.0, 4.0], CenterSampler())

The implementation must return a d-by-n matrix in the unit box. It must not add a competing bounds method, because the generic bounds method validates and scales the unit-box result.