CompositeSamplers.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.rng.sampling;
import java.util.List;
import java.util.Objects;
import java.util.ArrayList;
import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.sampling.distribution.AliasMethodDiscreteSampler;
import org.apache.commons.rng.sampling.distribution.ContinuousSampler;
import org.apache.commons.rng.sampling.distribution.DiscreteSampler;
import org.apache.commons.rng.sampling.distribution.DiscreteUniformSampler;
import org.apache.commons.rng.sampling.distribution.GuideTableDiscreteSampler;
import org.apache.commons.rng.sampling.distribution.LongSampler;
import org.apache.commons.rng.sampling.distribution.MarsagliaTsangWangDiscreteSampler;
import org.apache.commons.rng.sampling.distribution.SharedStateContinuousSampler;
import org.apache.commons.rng.sampling.distribution.SharedStateDiscreteSampler;
import org.apache.commons.rng.sampling.distribution.SharedStateLongSampler;
/**
* Factory class to create a sampler that combines sampling from multiple samplers.
*
* <p>The composite sampler is constructed using a {@link Builder builder} for the type of samplers
* that will form the composite. Each sampler has a weight in the composition.
* Samples are returned using a 2 step algorithm:
*
* <ol>
* <li>Select a sampler based on its weighting
* <li>Return a sample from the selected sampler
* </ol>
*
* <p>The weights used for each sampler create a discrete probability distribution. This is
* sampled using a discrete probability distribution sampler. The builder provides methods
* to change the default implementation.
*
* <p>The following example will create a sampler to uniformly sample the border of a triangle
* using the line segment lengths as weights:
*
* <pre>
* UniformRandomProvider rng = RandomSource.KISS.create();
* double[] a = {1.23, 4.56};
* double[] b = {6.78, 9.01};
* double[] c = {3.45, 2.34};
* ObjectSampler<double[]> sampler =
* CompositeSamplers.<double[]>newObjectSamplerBuilder()
* .add(LineSampler.of(rng, a, b), Math.hypot(a[0] - b[0], a[1] - b[1]))
* .add(LineSampler.of(rng, b, c), Math.hypot(b[0] - c[0], b[1] - c[1]))
* .add(LineSampler.of(rng, c, a), Math.hypot(c[0] - a[0], c[1] - a[1]))
* .build(rng);
* </pre>
*
* @since 1.4
*/
public final class CompositeSamplers {
/**
* A factory for creating a sampler of a user-defined
* <a href="http://en.wikipedia.org/wiki/Probability_distribution#Discrete_probability_distribution">
* discrete probability distribution</a>.
*/
public interface DiscreteProbabilitySamplerFactory {
/**
* Creates the sampler.
*
* @param rng Source of randomness.
* @param probabilities Discrete probability distribution.
* @return the sampler
*/
DiscreteSampler create(UniformRandomProvider rng,
double[] probabilities);
}
/**
* The DiscreteProbabilitySampler class defines implementations that sample from a user-defined
* <a href="http://en.wikipedia.org/wiki/Probability_distribution#Discrete_probability_distribution">
* discrete probability distribution</a>.
*
* <p>All implementations support the {@link SharedStateDiscreteSampler} interface.
*/
public enum DiscreteProbabilitySampler implements DiscreteProbabilitySamplerFactory {
/** Sample using a guide table (see {@link GuideTableDiscreteSampler}). */
GUIDE_TABLE {
@Override
public SharedStateDiscreteSampler create(UniformRandomProvider rng, double[] probabilities) {
return GuideTableDiscreteSampler.of(rng, probabilities);
}
},
/** Sample using the alias method (see {@link AliasMethodDiscreteSampler}). */
ALIAS_METHOD {
@Override
public SharedStateDiscreteSampler create(UniformRandomProvider rng, double[] probabilities) {
return AliasMethodDiscreteSampler.of(rng, probabilities);
}
},
/**
* Sample using an optimised look-up table (see
* {@link org.apache.commons.rng.sampling.distribution.MarsagliaTsangWangDiscreteSampler.Enumerated
* MarsagliaTsangWangDiscreteSampler.Enumerated}).
*/
LOOKUP_TABLE {
@Override
public SharedStateDiscreteSampler create(UniformRandomProvider rng, double[] probabilities) {
return MarsagliaTsangWangDiscreteSampler.Enumerated.of(rng, probabilities);
}
}
}
/**
* A class to implement the SharedStateDiscreteSampler interface for a discrete probability
* sampler given a factory and the probability distribution. Each new instance will recreate
* the distribution sampler using the factory.
*/
private static class SharedStateDiscreteProbabilitySampler implements SharedStateDiscreteSampler {
/** The sampler. */
private final DiscreteSampler sampler;
/** The factory to create a new discrete sampler. */
private final DiscreteProbabilitySamplerFactory factory;
/** The probabilities. */
private final double[] probabilities;
/**
* @param sampler Sampler of the discrete distribution.
* @param factory Factory to create a new discrete sampler.
* @param probabilities Probabilities of the discrete distribution.
* @throws NullPointerException if the {@code sampler} is null
*/
SharedStateDiscreteProbabilitySampler(DiscreteSampler sampler,
DiscreteProbabilitySamplerFactory factory,
double[] probabilities) {
this.sampler = Objects.requireNonNull(sampler, "discrete sampler");
// Assume the factory and probabilities are not null
this.factory = factory;
this.probabilities = probabilities;
}
@Override
public int sample() {
// Delegate
return sampler.sample();
}
@Override
public SharedStateDiscreteSampler withUniformRandomProvider(UniformRandomProvider rng) {
// The factory may destructively modify the probabilities
return new SharedStateDiscreteProbabilitySampler(factory.create(rng, probabilities.clone()),
factory, probabilities);
}
}
/**
* Builds a composite sampler.
*
* <p>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:
*
* <ol>
* <li>Select a sampler based on its weighting
* <li>Return a sample from the selected sampler
* </ol>
*
* <p>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:
* <pre>
* p(i) = w(i) / sum(w)
* </pre>
*
* <p>The builder provides a method to set the factory used to generate the discrete sampler.
*
* @param <S> Type of sampler
*/
public interface Builder<S> {
/**
* Return the number of samplers in the composite. The size must be non-zero before
* the {@link #build(UniformRandomProvider) build} method can create a sampler.
*
* @return the size
*/
int size();
/**
* Adds the sampler to the composite. A sampler with a zero weight is ignored.
*
* @param sampler Sampler.
* @param weight Weight for the composition.
* @return a reference to this builder
* @throws IllegalArgumentException if {@code weight} is negative, infinite or {@code NaN}.
* @throws NullPointerException if {@code sampler} is null.
*/
Builder<S> add(S sampler, double weight);
/**
* Sets the factory to use to generate the composite's discrete sampler from the sampler
* weights.
*
* <p>Note: If the factory is not explicitly set then a default will be used.
*
* @param factory Factory.
* @return a reference to this builder
* @throws NullPointerException if {@code factory} is null.
*/
Builder<S> setFactory(DiscreteProbabilitySamplerFactory factory);
/**
* Builds the composite sampler. The {@code rng} is the source of randomness for selecting
* which sampler to use for each sample.
*
* <p>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.
*
* @param rng Generator of uniformly distributed random numbers.
* @return the sampler
* @throws IllegalStateException if no samplers have been added to create a composite.
* @see #size()
*/
S build(UniformRandomProvider rng);
}
/**
* Builds a composite sampler.
*
* <p>A single builder can be used to create composites of different implementing classes
* which support different sampler interfaces. The type of sampler is generic. The individual
* samplers and their weights can be collected by the builder. The build method creates
* the discrete probability distribution from the weights. The final composite is created
* using a factory to create the class.
*
* @param <S> Type of sampler
*/
private static class SamplerBuilder<S> implements Builder<S> {
/** The specialisation of the sampler. */
private final Specialisation specialisation;
/** The weighted samplers. */
private final List<WeightedSampler<S>> weightedSamplers;
/** The factory to create the discrete probability sampler from the weights. */
private DiscreteProbabilitySamplerFactory factory;
/** The factory to create the composite sampler. */
private final SamplerFactory<S> compositeFactory;
/**
* The specialisation of composite sampler to build.
* This is used to determine if specialised interfaces from the sampler
* type must be supported, e.g. {@link SharedStateSampler}.
*/
enum Specialisation {
/** Instance of {@link SharedStateSampler}. */
SHARED_STATE_SAMPLER,
/** No specialisation. */
NONE
}
/**
* A factory for creating composite samplers.
*
* <p>This interface is used to build concrete implementations
* of different sampler interfaces.
*
* @param <S> Type of sampler
*/
interface SamplerFactory<S> {
/**
* Creates a new composite sampler.
*
* <p>If the composite specialisation is a
* {@link Specialisation#SHARED_STATE_SAMPLER shared state sampler}
* the discrete sampler passed to this method will be an instance of
* {@link SharedStateDiscreteSampler}.
*
* @param discreteSampler Discrete sampler.
* @param samplers Samplers.
* @return the sampler
*/
S createSampler(DiscreteSampler discreteSampler,
List<S> samplers);
}
/**
* Contains a weighted sampler.
*
* @param <S> Sampler type
*/
private static class WeightedSampler<S> {
/** The weight. */
private final double weight;
/** The sampler. */
private final S sampler;
/**
* @param weight the weight
* @param sampler the sampler
* @throws IllegalArgumentException if {@code weight} is negative, infinite or {@code NaN}.
* @throws NullPointerException if {@code sampler} is null.
*/
WeightedSampler(double weight, S sampler) {
this.weight = requirePositiveFinite(weight, "weight");
this.sampler = Objects.requireNonNull(sampler, "sampler");
}
/**
* Gets the weight.
*
* @return the weight
*/
double getWeight() {
return weight;
}
/**
* Gets the sampler.
*
* @return the sampler
*/
S getSampler() {
return sampler;
}
/**
* Checks that the specified value is positive finite and throws a customized
* {@link IllegalArgumentException} if it is not.
*
* @param value the value
* @param message detail message to be used in the event that a {@code
* IllegalArgumentException} is thrown
* @return {@code value} if positive finite
* @throws IllegalArgumentException if {@code weight} is negative, infinite or {@code NaN}.
*/
private static double requirePositiveFinite(double value, String message) {
// Must be positive finite
if (!(value >= 0 && value < Double.POSITIVE_INFINITY)) {
throw new IllegalArgumentException(message + " is not positive finite: " + value);
}
return value;
}
}
/**
* @param specialisation Specialisation of the sampler.
* @param compositeFactory Factory to create the final composite sampler.
*/
SamplerBuilder(Specialisation specialisation,
SamplerFactory<S> compositeFactory) {
this.specialisation = specialisation;
this.compositeFactory = compositeFactory;
weightedSamplers = new ArrayList<>();
factory = DiscreteProbabilitySampler.GUIDE_TABLE;
}
@Override
public int size() {
return weightedSamplers.size();
}
@Override
public Builder<S> add(S sampler, double weight) {
// Ignore zero weights. The sampler and weight are validated by the WeightedSampler.
if (weight != 0) {
weightedSamplers.add(new WeightedSampler<>(weight, sampler));
}
return this;
}
/**
* {@inheritDoc}
*
* <p>If the weights are uniform the factory is ignored and composite's discrete sampler
* is a {@link DiscreteUniformSampler uniform distribution sampler}.
*/
@Override
public Builder<S> setFactory(DiscreteProbabilitySamplerFactory samplerFactory) {
this.factory = Objects.requireNonNull(samplerFactory, "factory");
return this;
}
/**
* {@inheritDoc}
*
* <p>If only one sampler has been added to the builder then the sampler is returned
* and the builder is reset.
*
* @throws IllegalStateException if no samplers have been added to create a composite.
*/
@Override
public S build(UniformRandomProvider rng) {
final List<WeightedSampler<S>> list = this.weightedSamplers;
final int n = list.size();
if (n == 0) {
throw new IllegalStateException("No samplers to build the composite");
}
if (n == 1) {
// No composite
final S sampler = list.get(0).sampler;
reset();
return sampler;
}
// Extract the weights and samplers.
final double[] weights = new double[n];
final ArrayList<S> samplers = new ArrayList<>(n);
for (int i = 0; i < n; i++) {
final WeightedSampler<S> weightedItem = list.get(i);
weights[i] = weightedItem.getWeight();
samplers.add(weightedItem.getSampler());
}
reset();
final DiscreteSampler discreteSampler = createDiscreteSampler(rng, weights);
return compositeFactory.createSampler(discreteSampler, samplers);
}
/**
* Reset the builder.
*/
private void reset() {
weightedSamplers.clear();
}
/**
* Creates the discrete sampler of the enumerated probability distribution.
*
* <p>If the specialisation is a {@link Specialisation#SHARED_STATE_SAMPLER shared state sampler}
* the discrete sampler will be an instance of {@link SharedStateDiscreteSampler}.
*
* @param rng Generator of uniformly distributed random numbers.
* @param weights Weight associated to each item.
* @return the sampler
*/
private DiscreteSampler createDiscreteSampler(UniformRandomProvider rng,
double[] weights) {
// Edge case. Detect uniform weights.
final int n = weights.length;
if (uniform(weights)) {
// Uniformly sample from the size.
// Note: Upper bound is inclusive.
return DiscreteUniformSampler.of(rng, 0, n - 1);
}
// If possible normalise with a simple sum.
final double sum = sum(weights);
if (sum < Double.POSITIVE_INFINITY) {
// Do not use f = 1.0 / sum and multiplication by f.
// Use of divide handles a sub-normal sum.
for (int i = 0; i < n; i++) {
weights[i] /= sum;
}
} else {
// The sum is not finite. We know the weights are all positive finite.
// Compute the mean without overflow and divide by the mean and number of items.
final double mean = mean(weights);
for (int i = 0; i < n; i++) {
// Two step division avoids using the denominator (mean * n)
weights[i] = weights[i] / mean / n;
}
}
// Create the sampler from the factory.
// Check if a SharedStateSampler is required.
// If a default factory then the result is a SharedStateDiscreteSampler,
// otherwise the sampler must be checked.
if (specialisation == Specialisation.SHARED_STATE_SAMPLER &&
!(factory instanceof DiscreteProbabilitySampler)) {
// If the factory was user defined then clone the weights as they may be required
// to create a SharedStateDiscreteProbabilitySampler.
final DiscreteSampler sampler = factory.create(rng, weights.clone());
return sampler instanceof SharedStateDiscreteSampler ?
sampler :
new SharedStateDiscreteProbabilitySampler(sampler, factory, weights);
}
return factory.create(rng, weights);
}
/**
* Check if all the values are the same.
*
* <p>Warning: This method assumes there are input values. If the length is zero an
* {@link ArrayIndexOutOfBoundsException} will be thrown.
*
* @param values the values
* @return true if all values are the same
*/
private static boolean uniform(double[] values) {
final double value = values[0];
for (int i = 1; i < values.length; i++) {
if (value != values[i]) {
return false;
}
}
return true;
}
/**
* Compute the sum of the values.
*
* @param values the values
* @return the sum
*/
private static double sum(double[] values) {
double sum = 0;
for (final double value : values) {
sum += value;
}
return sum;
}
/**
* Compute the mean of the values. Uses a rolling algorithm to avoid overflow of a simple sum.
* This method can be used to compute the mean of observed counts for normalisation to a
* probability:
*
* <pre>
* double[] values = ...;
* int n = values.length;
* double mean = mean(values);
* for (int i = 0; i < n; i++) {
* // Two step division avoids using the denominator (mean * n)
* values[i] = values[i] / mean / n;
* }
* </pre>
*
* <p>Warning: This method assumes there are input values. If the length is zero an
* {@link ArrayIndexOutOfBoundsException} will be thrown.
*
* @param values the values
* @return the mean
*/
private static double mean(double[] values) {
double mean = values[0];
int i = 1;
while (i < values.length) {
// Deviation from the mean
final double dev = values[i] - mean;
i++;
mean += dev / i;
}
return mean;
}
}
/**
* A composite sampler.
*
* <p>The source sampler for each sampler is chosen based on a user-defined continuous
* probability distribution.
*
* @param <S> Type of sampler
*/
private static class CompositeSampler<S> {
/** Continuous sampler to choose the individual sampler to sample. */
protected final DiscreteSampler discreteSampler;
/** Collection of samplers to be sampled from. */
protected final List<S> samplers;
/**
* @param discreteSampler Continuous sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeSampler(DiscreteSampler discreteSampler,
List<S> samplers) {
this.discreteSampler = discreteSampler;
this.samplers = samplers;
}
/**
* Gets the next sampler to use to create a sample.
*
* @return the sampler
*/
S nextSampler() {
return samplers.get(discreteSampler.sample());
}
}
/**
* A factory for creating a composite ObjectSampler.
*
* @param <T> Type of sample
*/
private static class ObjectSamplerFactory<T> implements
SamplerBuilder.SamplerFactory<ObjectSampler<T>> {
/** The instance. */
@SuppressWarnings("rawtypes")
private static final ObjectSamplerFactory INSTANCE = new ObjectSamplerFactory();
/**
* Get an instance.
*
* @param <T> Type of sample
* @return the factory
*/
@SuppressWarnings("unchecked")
static <T> ObjectSamplerFactory<T> instance() {
return (ObjectSamplerFactory<T>) INSTANCE;
}
@Override
public ObjectSampler<T> createSampler(DiscreteSampler discreteSampler,
List<ObjectSampler<T>> samplers) {
return new CompositeObjectSampler<>(discreteSampler, samplers);
}
/**
* A composite object sampler.
*
* @param <T> Type of sample
*/
private static class CompositeObjectSampler<T>
extends CompositeSampler<ObjectSampler<T>>
implements ObjectSampler<T> {
/**
* @param discreteSampler Discrete sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeObjectSampler(DiscreteSampler discreteSampler,
List<ObjectSampler<T>> samplers) {
super(discreteSampler, samplers);
}
@Override
public T sample() {
return nextSampler().sample();
}
}
}
/**
* A factory for creating a composite SharedStateObjectSampler.
*
* @param <T> Type of sample
*/
private static class SharedStateObjectSamplerFactory<T> implements
SamplerBuilder.SamplerFactory<SharedStateObjectSampler<T>> {
/** The instance. */
@SuppressWarnings("rawtypes")
private static final SharedStateObjectSamplerFactory INSTANCE = new SharedStateObjectSamplerFactory();
/**
* Get an instance.
*
* @param <T> Type of sample
* @return the factory
*/
@SuppressWarnings("unchecked")
static <T> SharedStateObjectSamplerFactory<T> instance() {
return (SharedStateObjectSamplerFactory<T>) INSTANCE;
}
@Override
public SharedStateObjectSampler<T> createSampler(DiscreteSampler discreteSampler,
List<SharedStateObjectSampler<T>> samplers) {
// The input discrete sampler is assumed to be a SharedStateDiscreteSampler
return new CompositeSharedStateObjectSampler<>(
(SharedStateDiscreteSampler) discreteSampler, samplers);
}
/**
* A composite object sampler with shared state support.
*
* <p>The source sampler for each sampler is chosen based on a user-defined
* discrete probability distribution.
*
* @param <T> Type of sample
*/
private static class CompositeSharedStateObjectSampler<T>
extends CompositeSampler<SharedStateObjectSampler<T>>
implements SharedStateObjectSampler<T> {
/**
* @param discreteSampler Discrete sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeSharedStateObjectSampler(SharedStateDiscreteSampler discreteSampler,
List<SharedStateObjectSampler<T>> samplers) {
super(discreteSampler, samplers);
}
@Override
public T sample() {
return nextSampler().sample();
}
@Override
public CompositeSharedStateObjectSampler<T> withUniformRandomProvider(UniformRandomProvider rng) {
// Duplicate each sampler with the same source of randomness
return new CompositeSharedStateObjectSampler<>(
((SharedStateDiscreteSampler) this.discreteSampler).withUniformRandomProvider(rng),
copy(samplers, rng));
}
}
}
/**
* A factory for creating a composite DiscreteSampler.
*/
private static class DiscreteSamplerFactory implements
SamplerBuilder.SamplerFactory<DiscreteSampler> {
/** The instance. */
static final DiscreteSamplerFactory INSTANCE = new DiscreteSamplerFactory();
@Override
public DiscreteSampler createSampler(DiscreteSampler discreteSampler,
List<DiscreteSampler> samplers) {
return new CompositeDiscreteSampler(discreteSampler, samplers);
}
/**
* A composite discrete sampler.
*/
private static class CompositeDiscreteSampler
extends CompositeSampler<DiscreteSampler>
implements DiscreteSampler {
/**
* @param discreteSampler Discrete sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeDiscreteSampler(DiscreteSampler discreteSampler,
List<DiscreteSampler> samplers) {
super(discreteSampler, samplers);
}
@Override
public int sample() {
return nextSampler().sample();
}
}
}
/**
* A factory for creating a composite SharedStateDiscreteSampler.
*/
private static class SharedStateDiscreteSamplerFactory implements
SamplerBuilder.SamplerFactory<SharedStateDiscreteSampler> {
/** The instance. */
static final SharedStateDiscreteSamplerFactory INSTANCE = new SharedStateDiscreteSamplerFactory();
@Override
public SharedStateDiscreteSampler createSampler(DiscreteSampler discreteSampler,
List<SharedStateDiscreteSampler> samplers) {
// The input discrete sampler is assumed to be a SharedStateDiscreteSampler
return new CompositeSharedStateDiscreteSampler(
(SharedStateDiscreteSampler) discreteSampler, samplers);
}
/**
* A composite discrete sampler with shared state support.
*/
private static class CompositeSharedStateDiscreteSampler
extends CompositeSampler<SharedStateDiscreteSampler>
implements SharedStateDiscreteSampler {
/**
* @param discreteSampler Discrete sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeSharedStateDiscreteSampler(SharedStateDiscreteSampler discreteSampler,
List<SharedStateDiscreteSampler> samplers) {
super(discreteSampler, samplers);
}
@Override
public int sample() {
return nextSampler().sample();
}
@Override
public CompositeSharedStateDiscreteSampler withUniformRandomProvider(UniformRandomProvider rng) {
// Duplicate each sampler with the same source of randomness
return new CompositeSharedStateDiscreteSampler(
((SharedStateDiscreteSampler) this.discreteSampler).withUniformRandomProvider(rng),
copy(samplers, rng));
}
}
}
/**
* A factory for creating a composite ContinuousSampler.
*/
private static class ContinuousSamplerFactory implements
SamplerBuilder.SamplerFactory<ContinuousSampler> {
/** The instance. */
static final ContinuousSamplerFactory INSTANCE = new ContinuousSamplerFactory();
@Override
public ContinuousSampler createSampler(DiscreteSampler discreteSampler,
List<ContinuousSampler> samplers) {
return new CompositeContinuousSampler(discreteSampler, samplers);
}
/**
* A composite continuous sampler.
*/
private static class CompositeContinuousSampler
extends CompositeSampler<ContinuousSampler>
implements ContinuousSampler {
/**
* @param discreteSampler Continuous sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeContinuousSampler(DiscreteSampler discreteSampler,
List<ContinuousSampler> samplers) {
super(discreteSampler, samplers);
}
@Override
public double sample() {
return nextSampler().sample();
}
}
}
/**
* A factory for creating a composite SharedStateContinuousSampler.
*/
private static class SharedStateContinuousSamplerFactory implements
SamplerBuilder.SamplerFactory<SharedStateContinuousSampler> {
/** The instance. */
static final SharedStateContinuousSamplerFactory INSTANCE = new SharedStateContinuousSamplerFactory();
@Override
public SharedStateContinuousSampler createSampler(DiscreteSampler discreteSampler,
List<SharedStateContinuousSampler> samplers) {
// The sampler is assumed to be a SharedStateContinuousSampler
return new CompositeSharedStateContinuousSampler(
(SharedStateDiscreteSampler) discreteSampler, samplers);
}
/**
* A composite continuous sampler with shared state support.
*/
private static class CompositeSharedStateContinuousSampler
extends CompositeSampler<SharedStateContinuousSampler>
implements SharedStateContinuousSampler {
/**
* @param discreteSampler Continuous sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeSharedStateContinuousSampler(SharedStateDiscreteSampler discreteSampler,
List<SharedStateContinuousSampler> samplers) {
super(discreteSampler, samplers);
}
@Override
public double sample() {
return nextSampler().sample();
}
@Override
public CompositeSharedStateContinuousSampler withUniformRandomProvider(UniformRandomProvider rng) {
// Duplicate each sampler with the same source of randomness
return new CompositeSharedStateContinuousSampler(
((SharedStateDiscreteSampler) this.discreteSampler).withUniformRandomProvider(rng),
copy(samplers, rng));
}
}
}
/**
* A factory for creating a composite LongSampler.
*/
private static class LongSamplerFactory implements
SamplerBuilder.SamplerFactory<LongSampler> {
/** The instance. */
static final LongSamplerFactory INSTANCE = new LongSamplerFactory();
@Override
public LongSampler createSampler(DiscreteSampler discreteSampler,
List<LongSampler> samplers) {
return new CompositeLongSampler(discreteSampler, samplers);
}
/**
* A composite long sampler.
*/
private static class CompositeLongSampler
extends CompositeSampler<LongSampler>
implements LongSampler {
/**
* @param discreteSampler Long sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeLongSampler(DiscreteSampler discreteSampler,
List<LongSampler> samplers) {
super(discreteSampler, samplers);
}
@Override
public long sample() {
return nextSampler().sample();
}
}
}
/**
* A factory for creating a composite SharedStateLongSampler.
*/
private static class SharedStateLongSamplerFactory implements
SamplerBuilder.SamplerFactory<SharedStateLongSampler> {
/** The instance. */
static final SharedStateLongSamplerFactory INSTANCE = new SharedStateLongSamplerFactory();
@Override
public SharedStateLongSampler createSampler(DiscreteSampler discreteSampler,
List<SharedStateLongSampler> samplers) {
// The input discrete sampler is assumed to be a SharedStateLongSampler
return new CompositeSharedStateLongSampler(
(SharedStateDiscreteSampler) discreteSampler, samplers);
}
/**
* A composite long sampler with shared state support.
*/
private static class CompositeSharedStateLongSampler
extends CompositeSampler<SharedStateLongSampler>
implements SharedStateLongSampler {
/**
* @param discreteSampler Long sampler to choose the individual sampler to sample.
* @param samplers Collection of samplers to be sampled from.
*/
CompositeSharedStateLongSampler(SharedStateDiscreteSampler discreteSampler,
List<SharedStateLongSampler> samplers) {
super(discreteSampler, samplers);
}
@Override
public long sample() {
return nextSampler().sample();
}
@Override
public CompositeSharedStateLongSampler withUniformRandomProvider(UniformRandomProvider rng) {
// Duplicate each sampler with the same source of randomness
return new CompositeSharedStateLongSampler(
((SharedStateDiscreteSampler) this.discreteSampler).withUniformRandomProvider(rng),
copy(samplers, rng));
}
}
}
/** No public instances. */
private CompositeSamplers() {}
/**
* Create a new builder for a composite {@link ObjectSampler}.
*
* <p>Note: If the compiler cannot infer the type parameter of the sampler it can be specified
* within the diamond operator {@code <T>} preceding the call to
* {@code newObjectSamplerBuilder()}, for example:
*
* <pre>{@code
* CompositeSamplers.<double[]>newObjectSamplerBuilder()
* }</pre>
*
* @param <T> Type of the sample.
* @return the builder
*/
public static <T> Builder<ObjectSampler<T>> newObjectSamplerBuilder() {
final SamplerBuilder.SamplerFactory<ObjectSampler<T>> factory = ObjectSamplerFactory.instance();
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.NONE, factory);
}
/**
* Create a new builder for a composite {@link SharedStateObjectSampler}.
*
* <p>Note: If the compiler cannot infer the type parameter of the sampler it can be specified
* within the diamond operator {@code <T>} preceding the call to
* {@code newSharedStateObjectSamplerBuilder()}, for example:
*
* <pre>{@code
* CompositeSamplers.<double[]>newSharedStateObjectSamplerBuilder()
* }</pre>
*
* @param <T> Type of the sample.
* @return the builder
*/
public static <T> Builder<SharedStateObjectSampler<T>> newSharedStateObjectSamplerBuilder() {
final SamplerBuilder.SamplerFactory<SharedStateObjectSampler<T>> factory =
SharedStateObjectSamplerFactory.instance();
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.SHARED_STATE_SAMPLER, factory);
}
/**
* Create a new builder for a composite {@link DiscreteSampler}.
*
* @return the builder
*/
public static Builder<DiscreteSampler> newDiscreteSamplerBuilder() {
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.NONE, DiscreteSamplerFactory.INSTANCE);
}
/**
* Create a new builder for a composite {@link SharedStateDiscreteSampler}.
*
* @return the builder
*/
public static Builder<SharedStateDiscreteSampler> newSharedStateDiscreteSamplerBuilder() {
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.SHARED_STATE_SAMPLER, SharedStateDiscreteSamplerFactory.INSTANCE);
}
/**
* Create a new builder for a composite {@link ContinuousSampler}.
*
* @return the builder
*/
public static Builder<ContinuousSampler> newContinuousSamplerBuilder() {
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.NONE, ContinuousSamplerFactory.INSTANCE);
}
/**
* Create a new builder for a composite {@link SharedStateContinuousSampler}.
*
* @return the builder
*/
public static Builder<SharedStateContinuousSampler> newSharedStateContinuousSamplerBuilder() {
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.SHARED_STATE_SAMPLER, SharedStateContinuousSamplerFactory.INSTANCE);
}
/**
* Create a new builder for a composite {@link LongSampler}.
*
* @return the builder
*/
public static Builder<LongSampler> newLongSamplerBuilder() {
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.NONE, LongSamplerFactory.INSTANCE);
}
/**
* Create a new builder for a composite {@link SharedStateLongSampler}.
*
* @return the builder
*/
public static Builder<SharedStateLongSampler> newSharedStateLongSamplerBuilder() {
return new SamplerBuilder<>(
SamplerBuilder.Specialisation.SHARED_STATE_SAMPLER, SharedStateLongSamplerFactory.INSTANCE);
}
/**
* Create a copy instance of each sampler in the list of samplers using the given
* uniform random provider as the source of randomness.
*
* @param <T> the type of sampler
* @param samplers Source to copy.
* @param rng Generator of uniformly distributed random numbers.
* @return the copy
*/
private static <T extends SharedStateSampler<T>> List<T> copy(List<T> samplers,
UniformRandomProvider rng) {
final ArrayList<T> newSamplers = new ArrayList<>(samplers.size());
for (final T s : samplers) {
newSamplers.add(s.withUniformRandomProvider(rng));
}
return newSamplers;
}
}