Package org.apache.commons.rng.sampling
Interface CompositeSamplers.Builder<S>
- Type Parameters:
S
- Type of sampler
- All Known Implementing Classes:
CompositeSamplers.SamplerBuilder
- 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:
- Select a sampler based on its weighting
- 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 TypeMethodDescriptionAdds the sampler to the composite.Builds the composite sampler.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 Details
-
size
int size()Return the number of samplers in the composite. The size must be non-zero before thebuild
method can create a sampler.- Returns:
- the size
-
add
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
- ifweight
is negative, infinite orNaN
.NullPointerException
- ifsampler
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
- iffactory
is null.
-
build
Builds the composite sampler. Therng
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:
-