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()
      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