Package org.apache.commons.rng.sampling.distribution

Class InternalUtils

java.lang.Object

org.apache.commons.rng.sampling.distribution.InternalUtils

final class InternalUtils
extends java.lang.Object

Functions used by some of the samplers. This class is not part of the public API, as it would be better to group these utilities in a dedicated component.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	InternalUtils.FactorialLog	Class for computing the natural logarithm of the factorial of n.

Field Summary

Fields

Modifier and Type	Field	Description
private static int	BEGIN_LOG_FACTORIALS	The first array index with a non-zero log factorial.
private static double	DOUBLE_MULTIPLIER	The multiplier to convert the least significant 53-bits of a long to a double.
private static double[]	LOG_FACTORIALS	All long-representable factorials, precomputed as the natural logarithm using Matlab R2023a VPA: log(vpa(x)).

Constructor Summary

Constructors

Modifier	Constructor	Description
private	InternalUtils()	Utility class.

Method Summary

Modifier and Type	Method	Description
(package private) static double	logFactorial(int n)
(package private) static double	makeDouble(long v)	Creates a double in the interval [0, 1) from a long value.
(package private) static double	makeNonZeroDouble(long v)	Creates a double in the interval (0, 1] from a long value.
(package private) static NormalizedGaussianSampler	newNormalizedGaussianSampler(NormalizedGaussianSampler sampler, UniformRandomProvider rng)	Create a new instance of the given sampler using SharedStateSampler.withUniformRandomProvider(UniformRandomProvider).
(package private) static double	requireFinite(double x, java.lang.String name)	Checks the value x is finite.
(package private) static double	requirePositive(double x, java.lang.String name)	Checks the value x >= 0.
(package private) static double	requirePositiveFinite(double x, java.lang.String name)	Checks the value x >= 0 and is finite.
(package private) static double	requireRange(double min, double max, double x, java.lang.String name)	Checks the value is within the range: min <= x < max.
(package private) static double	requireRangeClosed(double min, double max, double x, java.lang.String name)	Checks the value is within the closed range: min <= x <= max.
(package private) static double	requireStrictlyPositive(double x, java.lang.String name)	Checks the value x > 0.
(package private) static double	requireStrictlyPositiveFinite(double x, java.lang.String name)	Checks the value x > 0 and is finite.
(package private) static double	validateProbabilities(double[] probabilities)	Validate the probabilities sum to a finite positive number.

Methods inherited from class java.lang.Object

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

Field Detail

LOG_FACTORIALS

private static final double[] LOG_FACTORIALS

All long-representable factorials, precomputed as the natural logarithm using Matlab R2023a VPA: log(vpa(x)).

Note: This table could be any length. Previously this stored the long value of n!, not log(n!). Using the previous length maintains behaviour.

BEGIN_LOG_FACTORIALS

private static final int BEGIN_LOG_FACTORIALS

The first array index with a non-zero log factorial.

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 org.apache.commons.rng.core.util.NumberFactory.

See Also:

Constant Field Values

Constructor Detail

InternalUtils

private InternalUtils()

Utility class.

Method Detail

logFactorial

static double logFactorial(int n)

Parameters:

n - Argument.

Returns:

n!

Throws:

java.lang.IndexOutOfBoundsException - if the result is too large to be represented by a long (i.e. if n > 20), or n is negative.

validateProbabilities

static double validateProbabilities(double[] probabilities)

Validate the probabilities sum to a finite positive number.

Parameters:

probabilities - the probabilities

Returns:

the sum

Throws:

java.lang.IllegalArgumentException - if probabilities is null or empty, a probability is negative, infinite or NaN, or the sum of all probabilities is not strictly positive.

requireFinite

static double requireFinite(double x,
                            java.lang.String name)

Checks the value x is finite.

Parameters:

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x is non-finite

requirePositiveFinite

static double requirePositiveFinite(double x,
                                    java.lang.String name)

Checks the value x >= 0 and is finite. Note: This method allows x == -0.0.

Parameters:

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x < 0 or is non-finite

requireStrictlyPositiveFinite

static double requireStrictlyPositiveFinite(double x,
                                            java.lang.String name)

Checks the value x > 0 and is finite.

Parameters:

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x <= 0 or is non-finite

requirePositive

static double requirePositive(double x,
                              java.lang.String name)

Checks the value x >= 0. Note: This method allows x == -0.0.

Parameters:

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x < 0

requireStrictlyPositive

static double requireStrictlyPositive(double x,
                                      java.lang.String name)

Checks the value x > 0.

Parameters:

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x <= 0

requireRange

static double requireRange(double min,
                           double max,
                           double x,
                           java.lang.String name)

Checks the value is within the range: min <= x < max.

Parameters:

min - Minimum (inclusive).

max - Maximum (exclusive).

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x < min || x >= max.

requireRangeClosed

static double requireRangeClosed(double min,
                                 double max,
                                 double x,
                                 java.lang.String name)

Checks the value is within the closed range: min <= x <= max.

Parameters:

min - Minimum (inclusive).

max - Maximum (inclusive).

x - Value.

name - Name of the value.

Returns:

x

Throws:

java.lang.IllegalArgumentException - if x < min || x > max.

newNormalizedGaussianSampler

static NormalizedGaussianSampler newNormalizedGaussianSampler(NormalizedGaussianSampler sampler,
                                                              UniformRandomProvider rng)

Create a new instance of the given sampler using SharedStateSampler.withUniformRandomProvider(UniformRandomProvider).

Parameters:

sampler - Source sampler.

rng - Generator of uniformly distributed random numbers.

Returns:

the new sampler

Throws:

java.lang.UnsupportedOperationException - if the underlying sampler is not a SharedStateSampler or does not return a NormalizedGaussianSampler when sharing state.

makeDouble

static double makeDouble(long v)

Creates a double in the interval [0, 1) from a long value.

Parameters:

v - Number.

Returns:

a double value in the interval [0, 1).

makeNonZeroDouble

static double makeNonZeroDouble(long v)

Creates a double in the interval (0, 1] from a long value.

Parameters:

v - Number.

Returns:

a double value in the interval (0, 1].