Class CompositeSamplers.SamplerBuilder<S>

java.lang.Object
org.apache.commons.rng.sampling.CompositeSamplers.SamplerBuilder<S>
Type Parameters:
S - Type of sampler
All Implemented Interfaces:
CompositeSamplers.Builder<S>
Enclosing class:
CompositeSamplers

private static final class CompositeSamplers.SamplerBuilder<S> extends Object implements CompositeSamplers.Builder<S>
Builds a composite sampler.

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.

  • Field Details

  • Constructor Details

  • Method Details

    • size

      public int size()
      Description copied from interface: CompositeSamplers.Builder
      Return the number of samplers in the composite. The size must be non-zero before the build method can create a sampler.
      Specified by:
      size in interface CompositeSamplers.Builder<S>
      Returns:
      the size
    • add

      public CompositeSamplers.Builder<S> add(S sampler, double weight)
      Description copied from interface: CompositeSamplers.Builder
      Adds the sampler to the composite. A sampler with a zero weight is ignored.
      Specified by:
      add in interface CompositeSamplers.Builder<S>
      Parameters:
      sampler - Sampler.
      weight - Weight for the composition.
      Returns:
      a reference to this builder
    • setFactory

      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.

      If the weights are uniform the factory is ignored and composite's discrete sampler is a uniform distribution sampler.

      Specified by:
      setFactory in interface CompositeSamplers.Builder<S>
      Parameters:
      samplerFactory - Factory.
      Returns:
      a reference to this builder
    • build

      public 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.

      If only one sampler has been added to the builder then the sampler is returned and the builder is reset.

      Specified by:
      build in interface CompositeSamplers.Builder<S>
      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:
    • reset

      private void reset()
      Reset the builder.
    • createDiscreteSampler

      private DiscreteSampler createDiscreteSampler(UniformRandomProvider rng, double[] weights)
      Creates the discrete sampler of the enumerated probability distribution.

      If the specialisation is a shared state sampler the discrete sampler will be an instance of SharedStateDiscreteSampler.

      Parameters:
      rng - Generator of uniformly distributed random numbers.
      weights - Weight associated to each item.
      Returns:
      the sampler
    • uniform

      private static boolean uniform(double[] values)
      Check if all the values are the same.

      Warning: This method assumes there are input values. If the length is zero an ArrayIndexOutOfBoundsException will be thrown.

      Parameters:
      values - the values
      Returns:
      true if all values are the same
    • sum

      private static double sum(double[] values)
      Compute the sum of the values.
      Parameters:
      values - the values
      Returns:
      the sum
    • mean

      private static double mean(double[] values)
      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:
       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;
       }
       

      Warning: This method assumes there are input values. If the length is zero an ArrayIndexOutOfBoundsException will be thrown.

      Parameters:
      values - the values
      Returns:
      the mean