[RNG-128] UnitBallSampler

• Type: Improvement
• Status: Closed
• Priority: Minor
• Resolution: Implemented
• Fix Version/s: 1.4
• Component/s: sampling
• Assignee: Alex Herbert
• Reporter: Alex Herbert
• Created: 09/Apr/21 20:17
• Updated: 13/Sep/21 10:41
• Resolved: 13/Apr/21 07:47

Description

The UnitSphereSampler can generate isotropically distributed coordinates on the surface of a hypersphere of a given dimension.

I propose to create a UnitBallSampler to generate isotropically distributed coordinates within a hypersphere of a given dimension.

Wolfram describes a method that will work with any dimension and a method for 2 dimensions:

Ball Point Picking
Disk Point Picking

It also suggests that a simple rejection method when sampling inside an n-cube of length 2 may be faster for small dimensions.

Creating an abstract class with a factory method would allow the best performing sampler to be created for each dimension:

public abstract class UnitBallSampler implements
        SharedStateSampler<UnitBallSampler> {
    /**
     * @return a random Cartesian coordinate within the unit n-ball.
     */
    public double[] next() {
        // ...
    }

    /**
     * Create a unit n-ball sampler for the given dimension.
     *
     * @param dimension Space dimension.
     * @param rng Generator for the individual components of the coordinates. 
     * A shallow copy will be stored in this instance.
     * @throws IllegalArgumentException If {@code dimension <= 0}
     */
    public static UnitBallSampler of(int dimension,
                                     UniformRandomProvider rng) {
        // ...
    }
}

The UnitSphereSampler sample method is named nextVector. The corresponding method here could be:

• next
• nextVector
• nextCoordinate
• nextPoint
• sample
• ...

Issue Links

• is a child of: RNG-132 Package rng.sampling.shape for sampling coordinates from shapes
• relates to: RNG-153 Update the UnitBallSampler method to use an exponential deviate