You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2019/03/06 15:46:58 UTC
[commons-rng] 01/10: RNG-73: Add methods used from
UniformRandomProvider to the samplers.
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-rng.git
commit fbeeb08208c1f92f7ae395451f86a32f54564fe6
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Thu Feb 28 21:15:19 2019 +0000
RNG-73: Add methods used from UniformRandomProvider to the samplers.
---
.../commons/rng/sampling/CollectionSampler.java | 2 ++
.../commons/rng/sampling/CombinationSampler.java | 8 +++++---
.../DiscreteProbabilityCollectionSampler.java | 2 ++
.../org/apache/commons/rng/sampling/ListSampler.java | 10 +++++++++-
.../commons/rng/sampling/PermutationSampler.java | 8 ++++++--
.../commons/rng/sampling/SubsetSamplerUtils.java | 6 ++++--
.../commons/rng/sampling/UnitSphereSampler.java | 7 +++++++
.../distribution/AhrensDieterExponentialSampler.java | 2 ++
.../AhrensDieterMarsagliaTsangGammaSampler.java | 7 +++++++
.../distribution/BoxMullerGaussianSampler.java | 2 ++
.../distribution/BoxMullerLogNormalSampler.java | 2 ++
.../BoxMullerNormalizedGaussianSampler.java | 2 ++
.../rng/sampling/distribution/ChengBetaSampler.java | 2 ++
.../distribution/ContinuousUniformSampler.java | 2 ++
.../sampling/distribution/DiscreteUniformSampler.java | 4 ++++
.../rng/sampling/distribution/GeometricSampler.java | 10 ++++++----
.../InverseTransformContinuousSampler.java | 4 +++-
.../distribution/InverseTransformDiscreteSampler.java | 4 +++-
.../distribution/InverseTransformParetoSampler.java | 2 ++
.../distribution/LargeMeanPoissonSampler.java | 11 +++++++++--
.../MarsagliaNormalizedGaussianSampler.java | 2 ++
.../rng/sampling/distribution/PoissonSampler.java | 7 +++++++
.../sampling/distribution/PoissonSamplerCache.java | 19 +++++++++++++------
.../distribution/RejectionInversionZipfSampler.java | 2 ++
.../distribution/SmallMeanPoissonSampler.java | 8 +++++---
.../ZigguratNormalizedGaussianSampler.java | 11 +++++++++--
26 files changed, 119 insertions(+), 27 deletions(-)
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CollectionSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CollectionSampler.java
index 34c7247..54f9ee9 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CollectionSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CollectionSampler.java
@@ -26,6 +26,8 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Sampling from a {@link Collection}.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)}.</p>
+ *
* @param <T> Type of items in the collection.
*
* @since 1.0
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CombinationSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CombinationSampler.java
index 58d4fe8..eeae0d5 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CombinationSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/CombinationSampler.java
@@ -26,14 +26,16 @@ import org.apache.commons.rng.UniformRandomProvider;
* <p>A combination is a selection of items from a collection, such that (unlike
* permutations) the order of selection <strong>does not matter</strong>. This
* sampler can be used to generate a combination in an unspecified order and is
- * faster than the corresponding {@link PermutationSampler}.
+ * faster than the corresponding {@link PermutationSampler}.</p>
*
* <p>Note that the sample order is unspecified. For example a sample
* combination of 2 from 4 may return {@code [0,1]} or {@code [1,0]} as the two are
- * equivalent, and the order of a given combination may change in subsequent samples.
+ * equivalent, and the order of a given combination may change in subsequent samples.</p>
*
* <p>The sampler can be used to generate indices to select subsets where the
- * order of the subset is not important.
+ * order of the subset is not important.</p>
+ *
+ * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)}.</p>
*
* @see PermutationSampler
*/
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/DiscreteProbabilityCollectionSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/DiscreteProbabilityCollectionSampler.java
index f85ff14..9bdeaab 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/DiscreteProbabilityCollectionSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/DiscreteProbabilityCollectionSampler.java
@@ -32,6 +32,8 @@ import org.apache.commons.rng.UniformRandomProvider;
* Note that if all unique items are assigned the same probability,
* it is much more efficient to use {@link CollectionSampler}.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @param <T> Type of items in the collection.
*
* @since 1.1
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ListSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ListSampler.java
index 40e4ddd..db31105 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ListSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ListSampler.java
@@ -25,7 +25,7 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Sampling from a {@link List}.
*
- * This class also contains utilities for shuffling a {@link List} in-place.
+ * <p>This class also contains utilities for shuffling a {@link List} in-place.</p>
*
* @since 1.0
*/
@@ -45,6 +45,10 @@ public class ListSampler {
* contains identical objects, the sample may include repeats.
* </p>
*
+ * <p>
+ * Sampling uses {@link UniformRandomProvider#nextInt(int)}.
+ * </p>
+ *
* @param <T> Type of the list items.
* @param rng Generator of uniformly distributed random numbers.
* @param collection List to be sampled from.
@@ -89,6 +93,10 @@ public class ListSampler {
* The {@code start} and {@code pos} parameters select which part
* of the array is randomized and which is left untouched.
*
+ * <p>
+ * Sampling uses {@link UniformRandomProvider#nextInt(int)}.
+ * </p>
+ *
* @param <T> Type of the list items.
* @param rng Random number generator.
* @param list List whose entries will be shuffled (in-place).
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/PermutationSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/PermutationSampler.java
index a5a30c2..7cb72cc 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/PermutationSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/PermutationSampler.java
@@ -23,7 +23,9 @@ import org.apache.commons.rng.UniformRandomProvider;
* Class for representing <a href="https://en.wikipedia.org/wiki/Permutation">permutations</a>
* of a sequence of integers.
*
- * <p>This class also contains utilities for shuffling an {@code int[]} array in-place.
+ * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)}.</p>
+ *
+ * <p>This class also contains utilities for shuffling an {@code int[]} array in-place.</p>
*/
public class PermutationSampler {
/** Domain of the permutation. */
@@ -40,7 +42,7 @@ public class PermutationSampler {
* length {@code k} whose entries are selected randomly, without
* repetition, from the integers 0, 1, ..., {@code n}-1 (inclusive).
* The returned array represents a permutation of {@code n} taken
- * {@code k}.
+ * {@code k}.</p>
*
* @param rng Generator of uniformly distributed random numbers.
* @param n Domain of the permutation.
@@ -86,6 +88,8 @@ public class PermutationSampler {
* The {@code start} and {@code towardHead} parameters select which part
* of the array is randomized and which is left untouched.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)}.</p>
+ *
* @param rng Random number generator.
* @param list Array whose entries will be shuffled (in-place).
* @param start Index at which shuffling begins.
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/SubsetSamplerUtils.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/SubsetSamplerUtils.java
index 32d58a1..0ac25f0 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/SubsetSamplerUtils.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/SubsetSamplerUtils.java
@@ -31,7 +31,7 @@ final class SubsetSamplerUtils {
* Checks the subset of length {@code k} from {@code n} is valid.
*
* <p>If {@code n <= 0} or {@code k <= 0} or {@code k > n} then no subset
- * is required and an exception is raised.
+ * is required and an exception is raised.</p>
*
* @param n Size of the set.
* @param k Size of the subset.
@@ -57,7 +57,9 @@ final class SubsetSamplerUtils {
* shuffled section.
*
* <p>The returned combination will have a length of {@code steps} for
- * {@code upper=true}, or {@code domain.length - steps} otherwise.
+ * {@code upper=true}, or {@code domain.length - steps} otherwise.</p>
+ *
+ * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)}.</p>
*
* @param domain The domain.
* @param steps The number of shuffle steps.
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/UnitSphereSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/UnitSphereSampler.java
index 3dbdb03..661702b 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/UnitSphereSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/UnitSphereSampler.java
@@ -25,6 +25,13 @@ import org.apache.commons.rng.sampling.distribution.ZigguratNormalizedGaussianSa
* Generate vectors <a href="http://mathworld.wolfram.com/SpherePointPicking.html">
* isotropically located on the surface of a sphere</a>.
*
+ * <p>Sampling uses:</p>
+ *
+ * <ul>
+ * <li>{@link UniformRandomProvider#nextLong()}
+ * <li>{@link UniformRandomProvider#nextDouble()}
+ * </ul>
+ *
* @since 1.1
*/
public class UnitSphereSampler {
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterExponentialSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterExponentialSampler.java
index 56e57b4..3f8a2e7 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterExponentialSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterExponentialSampler.java
@@ -21,6 +21,8 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Sampling from an <a href="http://mathworld.wolfram.com/ExponentialDistribution.html">exponential distribution</a>.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*/
public class AhrensDieterExponentialSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterMarsagliaTsangGammaSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterMarsagliaTsangGammaSampler.java
index 946475b..bb17d54 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterMarsagliaTsangGammaSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AhrensDieterMarsagliaTsangGammaSampler.java
@@ -39,6 +39,13 @@ import org.apache.commons.rng.UniformRandomProvider;
* </li>
* </ul>
*
+ * <p>Sampling uses:</p>
+ *
+ * <ul>
+ * <li>{@link UniformRandomProvider#nextDouble()} (both algorithms)
+ * <li>{@link UniformRandomProvider#nextLong()} (only for {@code theta >= 1})
+ * </ul>
+ *
* @since 1.0
*/
public class AhrensDieterMarsagliaTsangGammaSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerGaussianSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerGaussianSampler.java
index c04f09a..b140823 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerGaussianSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerGaussianSampler.java
@@ -22,6 +22,8 @@ import org.apache.commons.rng.UniformRandomProvider;
* <a href="https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform">
* Box-Muller algorithm</a> for sampling from a Gaussian distribution.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*
* @deprecated Since version 1.1. Please use {@link BoxMullerNormalizedGaussianSampler}
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerLogNormalSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerLogNormalSampler.java
index fba683e..de8fc29 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerLogNormalSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerLogNormalSampler.java
@@ -23,6 +23,8 @@ import org.apache.commons.rng.UniformRandomProvider;
* log-normal distribution</a>.
* Uses {@link BoxMullerNormalizedGaussianSampler} as the underlying sampler.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*
* @deprecated Since version 1.1. Please use {@link LogNormalSampler} instead.
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.java
index 78a6b74..49824f2 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/BoxMullerNormalizedGaussianSampler.java
@@ -23,6 +23,8 @@ import org.apache.commons.rng.UniformRandomProvider;
* Box-Muller algorithm</a> for sampling from Gaussian distribution with
* mean 0 and standard deviation 1.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.1
*/
public class BoxMullerNormalizedGaussianSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ChengBetaSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ChengBetaSampler.java
index 8ed0e3e..fd68958 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ChengBetaSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ChengBetaSampler.java
@@ -29,6 +29,8 @@ import org.apache.commons.rng.UniformRandomProvider;
* </pre>
* </blockquote>
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*/
public class ChengBetaSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ContinuousUniformSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ContinuousUniformSampler.java
index 2c972f8..e7d749e 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ContinuousUniformSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ContinuousUniformSampler.java
@@ -21,6 +21,8 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Sampling from a uniform distribution.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*/
public class ContinuousUniformSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/DiscreteUniformSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/DiscreteUniformSampler.java
index 00e308b..2b5ea52 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/DiscreteUniformSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/DiscreteUniformSampler.java
@@ -22,6 +22,10 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Discrete uniform distribution sampler.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)} when
+ * the range {@code (upper - lower) <} {@link Integer#MAX_VALUE}, otherwise
+ * {@link UniformRandomProvider#nextInt()}.</p>
+ *
* @since 1.0
*/
public class DiscreteUniformSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GeometricSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GeometricSampler.java
index 92b8df2..f4683ac 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GeometricSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GeometricSampler.java
@@ -23,19 +23,21 @@ import org.apache.commons.rng.UniformRandomProvider;
* distribution</a>.
*
* <p>This distribution samples the number of failures before the first success taking values in the
- * set {@code [0, 1, 2, ...]}.
+ * set {@code [0, 1, 2, ...]}.</p>
*
* <p>The sample is computed using a related exponential distribution. If \( X \) is an
* exponentially distributed random variable with parameter \( \lambda \), then
* \( Y = \left \lfloor X \right \rfloor \) is a geometrically distributed random variable with
- * parameter \( p = 1 − e^\lambda \), with \( p \) the probability of success.
+ * parameter \( p = 1 − e^\lambda \), with \( p \) the probability of success.</p>
*
* <p>This sampler outperforms using the {@link InverseTransformDiscreteSampler} with an appropriate
- * Geometric inverse cumulative probability function.
+ * Geometric inverse cumulative probability function.</p>
*
* <p>Usage note: As the probability of success (\( p \)) tends towards zero the mean of the
* distribution (\( \frac{1-p}{p} \)) tends towards infinity and due to the use of {@code int}
- * for the sample this can result in truncation of the distribution.
+ * for the sample this can result in truncation of the distribution.</p>
+ *
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
*
* @see <a
* href="https://en.wikipedia.org/wiki/Geometric_distribution#Related_distributions">Geometric
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformContinuousSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformContinuousSampler.java
index ccaa138..5ba32fd 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformContinuousSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformContinuousSampler.java
@@ -24,7 +24,9 @@ import org.apache.commons.rng.UniformRandomProvider;
* inversion method</a>.
*
* It can be used to sample any distribution that provides access to its
- * <em>inverse cumulative probabilty function</em>.
+ * <em>inverse cumulative probability function</em>.
+ *
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
*
* <p>Example:</p>
* <pre><code>
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformDiscreteSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformDiscreteSampler.java
index 5c43b58..276fb8e 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformDiscreteSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformDiscreteSampler.java
@@ -24,7 +24,9 @@ import org.apache.commons.rng.UniformRandomProvider;
* inversion method</a>.
*
* It can be used to sample any distribution that provides access to its
- * <em>inverse cumulative probabilty function</em>.
+ * <em>inverse cumulative probability function</em>.
+ *
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
*
* <p>Example:</p>
* <pre><code>
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformParetoSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformParetoSampler.java
index 3b59483..4fd619b 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformParetoSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/InverseTransformParetoSampler.java
@@ -21,6 +21,8 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Sampling from a <a href="https://en.wikipedia.org/wiki/Pareto_distribution">Pareto distribution</a>.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*/
public class InverseTransformParetoSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/LargeMeanPoissonSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/LargeMeanPoissonSampler.java
index 47ecab7..52af0ed 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/LargeMeanPoissonSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/LargeMeanPoissonSampler.java
@@ -32,9 +32,16 @@ import org.apache.commons.rng.sampling.distribution.InternalUtils.FactorialLog;
* </li>
* </ul>
*
- * @since 1.1
+ * <p>This sampler is suitable for {@code mean >= 40}.</p>
+ *
+ * <p>Sampling uses:</p>
+ *
+ * <ul>
+ * <li>{@link UniformRandomProvider#nextLong()}
+ * <li>{@link UniformRandomProvider#nextDouble()}
+ * </ul>
*
- * This sampler is suitable for {@code mean >= 40}.
+ * @since 1.1
*/
public class LargeMeanPoissonSampler
implements DiscreteSampler {
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.java
index 4b64461..af50b55 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/MarsagliaNormalizedGaussianSampler.java
@@ -25,6 +25,8 @@ import org.apache.commons.rng.UniformRandomProvider;
* This is a variation of the algorithm implemented in
* {@link BoxMullerNormalizedGaussianSampler}.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.1
*/
public class MarsagliaNormalizedGaussianSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSampler.java
index 2889108..599e1cd 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSampler.java
@@ -36,6 +36,13 @@ import org.apache.commons.rng.UniformRandomProvider;
* </li>
* </ul>
*
+ * <p>Sampling uses:</p>
+ *
+ * <ul>
+ * <li>{@link UniformRandomProvider#nextDouble()}
+ * <li>{@link UniformRandomProvider#nextLong()} (large means only)
+ * </ul>
+ *
* @since 1.0
*/
public class PoissonSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSamplerCache.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSamplerCache.java
index 130feac..61aa73b 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSamplerCache.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/PoissonSamplerCache.java
@@ -25,14 +25,14 @@ import org.apache.commons.rng.sampling.distribution.LargeMeanPoissonSampler.Larg
* distribution</a> using a cache to minimise construction cost.
*
* <p>The cache will return a sampler equivalent to
- * {@link PoissonSampler#PoissonSampler(UniformRandomProvider, double)}.
+ * {@link PoissonSampler#PoissonSampler(UniformRandomProvider, double)}.</p>
*
* <p>The cache allows the {@link PoissonSampler} construction cost to be minimised
* for low size Poisson samples. The cache stores state for a range of integers where
* integer value {@code n} can be used to construct a sampler for the range
- * {@code n <= mean < n+1}.
+ * {@code n <= mean < n+1}.</p>
*
- * <p>The cache is advantageous under the following conditions:
+ * <p>The cache is advantageous under the following conditions:</p>
*
* <ul>
* <li>The mean of the Poisson distribution falls within a known range.
@@ -44,15 +44,22 @@ import org.apache.commons.rng.sampling.distribution.LargeMeanPoissonSampler.Larg
*
* <p>If the sample size to be made with the <strong>same</strong> sampler is large
* then the construction cost is low compared to the sampling time and the cache
- * has minimal benefit.
+ * has minimal benefit.</p>
*
* <p>Performance improvement is dependent on the speed of the
* {@link UniformRandomProvider}. A fast provider can obtain a two-fold speed
- * improvement for a single-use Poisson sampler.
+ * improvement for a single-use Poisson sampler.</p>
*
* <p>The cache is thread safe. Note that concurrent threads using the cache
* must ensure a thread safe {@link UniformRandomProvider} is used when creating
- * samplers, e.g. a unique sampler per thread.
+ * samplers, e.g. a unique sampler per thread.</p>
+ *
+ * <p>Sampling uses:</p>
+ *
+ * <ul>
+ * <li>{@link UniformRandomProvider#nextDouble()}
+ * <li>{@link UniformRandomProvider#nextLong()} (large means only)
+ * </ul>
*
* @since 1.2
*/
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/RejectionInversionZipfSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/RejectionInversionZipfSampler.java
index 2e25934..d948c4b 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/RejectionInversionZipfSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/RejectionInversionZipfSampler.java
@@ -22,6 +22,8 @@ import org.apache.commons.rng.UniformRandomProvider;
/**
* Implementation of the <a href="https://en.wikipedia.org/wiki/Zipf's_law">Zipf distribution</a>.
*
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
+ *
* @since 1.0
*/
public class RejectionInversionZipfSampler
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/SmallMeanPoissonSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/SmallMeanPoissonSampler.java
index 15a0d69..607feef 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/SmallMeanPoissonSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/SmallMeanPoissonSampler.java
@@ -29,10 +29,12 @@ import org.apache.commons.rng.UniformRandomProvider;
* </li>
* </ul>
*
- * @since 1.1
+ * <p>This sampler is suitable for {@code mean < 40}.
+ * For large means, {@link LargeMeanPoissonSampler} should be used instead.</p>
+ *
+ * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
*
- * This sampler is suitable for {@code mean < 40}.
- * For large means, {@link LargeMeanPoissonSampler} should be used instead.
+ * @since 1.1
*/
public class SmallMeanPoissonSampler
implements DiscreteSampler {
diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.java
index cbd5e06..bd7345d 100644
--- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.java
+++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/ZigguratNormalizedGaussianSampler.java
@@ -24,9 +24,16 @@ import org.apache.commons.rng.UniformRandomProvider;
* Marsaglia and Tsang "Ziggurat" method</a> for sampling from a Gaussian
* distribution with mean 0 and standard deviation 1.
*
- * The algorithm is explained in this
+ * <p>The algorithm is explained in this
* <a href="http://www.jstatsoft.org/article/view/v005i08/ziggurat.pdf">paper</a>
- * and this implementation has been adapted from the C code provided therein.
+ * and this implementation has been adapted from the C code provided therein.</p>
+ *
+ * <p>Sampling uses:</p>
+ *
+ * <ul>
+ * <li>{@link UniformRandomProvider#nextLong()}
+ * <li>{@link UniformRandomProvider#nextDouble()}
+ * </ul>
*
* @since 1.1
*/