Class UnitSphereSampler

java.lang.Object
org.apache.commons.rng.sampling.UnitSphereSampler
All Implemented Interfaces:
ObjectSampler<double[]>, SharedStateObjectSampler<double[]>, SharedStateSampler<SharedStateObjectSampler<double[]>>
Direct Known Subclasses:
UnitSphereSampler.UnitSphereSampler1D, UnitSphereSampler.UnitSphereSampler2D, UnitSphereSampler.UnitSphereSampler3D, UnitSphereSampler.UnitSphereSamplerND

public class UnitSphereSampler extends Object implements SharedStateObjectSampler<double[]>
Generate vectors isotropically located on the surface of a sphere.

Sampling in 2 or more dimensions uses:

Sampling in 1D uses the sign bit from UniformRandomProvider.nextInt() to set the direction of the vector.

Since:
1.1
  • Field Details

    • ONE_D

      private static final int ONE_D
      The dimension for 1D sampling.
      See Also:
    • TWO_D

      private static final int TWO_D
      The dimension for 2D sampling.
      See Also:
    • THREE_D

      private static final int THREE_D
      The dimension for 3D sampling.
      See Also:
    • MASK_BIT_2

      private static final int MASK_BIT_2
      The mask to extract the second bit from an integer (naming starts at bit 1 for the least significant bit). The masked integer will have a value 0 or 2.
      See Also:
    • delegate

      private final UnitSphereSampler delegate
      The internal sampler optimised for the dimension.
  • Constructor Details

    • UnitSphereSampler

      @Deprecated public UnitSphereSampler(int dimension, UniformRandomProvider rng)
      This instance delegates sampling. Use the factory method of(UniformRandomProvider, int) to create an optimal sampler.
      Parameters:
      dimension - Space dimension.
      rng - Generator for the individual components of the vectors. A shallow copy will be stored in this instance.
      Throws:
      IllegalArgumentException - If dimension <= 0
    • UnitSphereSampler

      private UnitSphereSampler(UnitSphereSampler delegate)
      Private constructor used by deprecated constructor used to prevent partially initialized object if the construction of the delegate throws. In future versions the public constructor should be removed and the class made abstract.
      Parameters:
      delegate - Delegate.
    • UnitSphereSampler

      private UnitSphereSampler()
      Private constructor used by sub-class specialisations. In future versions the public constructor should be removed and the class made abstract.
  • Method Details

    • sample

      public double[] sample()
      Description copied from interface: ObjectSampler
      Create an object sample.
      Specified by:
      sample in interface ObjectSampler<double[]>
      Returns:
      a random normalized Cartesian vector.
      Since:
      1.4
    • nextVector

      @Deprecated public double[] nextVector()
      Deprecated.
      Returns:
      a random normalized Cartesian vector.
    • withUniformRandomProvider

      public UnitSphereSampler withUniformRandomProvider(UniformRandomProvider rng)
      Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.
      Specified by:
      withUniformRandomProvider in interface SharedStateSampler<SharedStateObjectSampler<double[]>>
      Parameters:
      rng - Generator of uniformly distributed random numbers.
      Returns:
      the sampler
      Since:
      1.3
    • of

      public static UnitSphereSampler of(UniformRandomProvider rng, int dimension)
      Create a unit sphere sampler for the given dimension.
      Parameters:
      rng - Generator for the individual components of the vectors. A shallow copy will be stored in the sampler.
      dimension - Space dimension.
      Returns:
      the sampler
      Throws:
      IllegalArgumentException - If dimension <= 0
      Since:
      1.4