Package org.apache.commons.rng.sampling

Interface CompositeSamplers.Builder<S>

Type Parameters:

S - Type of sampler

Enclosing class:

CompositeSamplers

public static interface CompositeSamplers.Builder<S>

Builds a composite sampler.

A composite sampler is a combination of multiple samplers that all return the same sample type. Each sampler has a weighting in the composition. Samples are returned using a 2 step algorithm:

1. Select a sampler based on its weighting
2. Return a sample from the selected sampler

Step 1 requires a discrete sampler constructed from a discrete probability distribution. The probability for each sampler is the sampler weight divided by the sum of the weights:

 p(i) = w(i) / sum(w)
 

The builder provides a method to set the factory used to generate the discrete sampler.

Method Summary

Modifier and Type	Method	Description
CompositeSamplers.Builder<S>	add(S sampler, double weight)	Adds the sampler to the composite.
S	build(UniformRandomProvider rng)	Builds the composite sampler.
CompositeSamplers.Builder<S>	setFactory(CompositeSamplers.DiscreteProbabilitySamplerFactory factory)	Sets the factory to use to generate the composite's discrete sampler from the sampler weights.
int	size()	Return the number of samplers in the composite.

Method Detail

size

int size()

Return the number of samplers in the composite. The size must be non-zero before the build method can create a sampler.

Returns:

the size

add

CompositeSamplers.Builder<S> add(S sampler,
                                 double weight)

Adds the sampler to the composite. A sampler with a zero weight is ignored.

Parameters:

sampler - Sampler.

weight - Weight for the composition.

Returns:

a reference to this builder

Throws:

IllegalArgumentException - if weight is negative, infinite or NaN.

NullPointerException - if sampler is null.

setFactory

CompositeSamplers.Builder<S> setFactory(CompositeSamplers.DiscreteProbabilitySamplerFactory factory)

Sets the factory to use to generate the composite's discrete sampler from the sampler weights.

Note: If the factory is not explicitly set then a default will be used.

Parameters:

factory - Factory.

Returns:

a reference to this builder

Throws:

NullPointerException - if factory is null.

build

S build(UniformRandomProvider rng)

Builds the composite sampler. The rng is the source of randomness for selecting which sampler to use for each sample.

Note: When the sampler is created the builder is reset to an empty state. This prevents building multiple composite samplers with the same samplers and their identical underlying source of randomness.

Parameters:

rng - Generator of uniformly distributed random numbers.

Returns:

the sampler

Throws:

IllegalStateException - if no samplers have been added to create a composite.

See Also:

size()