Package org.apache.commons.rng.sampling.shape

Class UnitBallSampler

java.lang.Object

org.apache.commons.rng.sampling.shape.UnitBallSampler

All Implemented Interfaces:

ObjectSampler<double[]>, SharedStateObjectSampler<double[]>, SharedStateSampler<SharedStateObjectSampler<double[]>>

Direct Known Subclasses:

UnitBallSampler.UnitBallSampler1D, UnitBallSampler.UnitBallSampler2D, UnitBallSampler.UnitBallSampler3D, UnitBallSampler.UnitBallSamplerND

public abstract class UnitBallSampler
extends java.lang.Object
implements SharedStateObjectSampler<double[]>

Generate coordinates uniformly distributed within the unit n-ball.

Sampling uses:

• UniformRandomProvider.nextLong()
• UniformRandomProvider.nextDouble() (only for dimensions above 2)

Since:

1.4

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	UnitBallSampler.UnitBallSampler1D	Sample uniformly from a 1D unit line.
private static class	UnitBallSampler.UnitBallSampler2D	Sample uniformly from a 2D unit disk.
private static class	UnitBallSampler.UnitBallSampler3D	Sample uniformly from a 3D unit ball.
private static class	UnitBallSampler.UnitBallSamplerND	Sample using ball point picking.

Field Summary

Fields

Modifier and Type	Field	Description
private static double	DOUBLE_MULTIPLIER	The multiplier to convert the least significant 53-bits of a long to a double.
private static int	ONE_D	The dimension for 1D sampling.
private static int	THREE_D	The dimension for 3D sampling.
private static int	TWO_D	The dimension for 2D sampling.

Constructor Summary

Constructors

Constructor	Description
UnitBallSampler()	Create an instance.

Method Summary

Modifier and Type	Method	Description
private static double	makeSignedDouble(long bits)	Creates a signed double in the range [-1, 1).
static UnitBallSampler	of(UniformRandomProvider rng, int dimension)	Create a unit n-ball sampler for the given dimension.
abstract double[]	sample()	Create an object sample.
abstract UnitBallSampler	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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.rng.sampling.ObjectSampler

samples, samples

Field Detail

ONE_D

private static final int ONE_D

The dimension for 1D sampling.

See Also:

Constant Field Values

TWO_D

private static final int TWO_D

The dimension for 2D sampling.

See Also:

Constant Field Values

THREE_D

private static final int THREE_D

The dimension for 3D sampling.

See Also:

Constant Field Values

DOUBLE_MULTIPLIER

private static final double DOUBLE_MULTIPLIER

The multiplier to convert the least significant 53-bits of a long to a double. Taken from o.a.c.rng.core.utils.NumberFactory.

This is equivalent to 1.0 / (1L << 53).

See Also:

Constant Field Values

Constructor Detail

UnitBallSampler

public UnitBallSampler()

Create an instance.

Method Detail

sample

public abstract double[] sample()

Description copied from interface: ObjectSampler

Create an object sample.

Specified by:

sample in interface ObjectSampler<double[]>

Returns:

a random Cartesian coordinate within the unit n-ball.

withUniformRandomProvider

public abstract UnitBallSampler 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

of

public static UnitBallSampler of(UniformRandomProvider rng,
                                 int dimension)

Create a unit n-ball sampler for the given dimension. Sampled points are uniformly distributed within the unit n-ball.

Sampling is supported in dimensions of 1 or above.

Parameters:

rng - Source of randomness.

dimension - Space dimension.

Returns:

the sampler

Throws:

java.lang.IllegalArgumentException - If dimension <= 0

makeSignedDouble

private static double makeSignedDouble(long bits)

Creates a signed double in the range [-1, 1). The magnitude is sampled evenly from the 2⁵⁴ dyadic rationals in the range.

Note: This method will not return samples for both -0.0 and 0.0.

Parameters:

bits - the bits

Returns:

the double