This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-rng.git
commit 934e7e4120eafb1982b43b75029b4463b9d7be18 Author: Alex Herbert <[email protected]> AuthorDate: Wed Aug 26 10:06:20 2026 +0100 RNG-202: Document effects of scaling factors --- .../sampling/distribution/AliasMethodDiscreteSampler.java | 9 +++++++++ .../sampling/distribution/GuideTableDiscreteSampler.java | 13 +++++++++++-- src/changes/changes.xml | 5 +++++ 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AliasMethodDiscreteSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AliasMethodDiscreteSampler.java index e09dccd2..6529321c 100644 --- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AliasMethodDiscreteSampler.java +++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/AliasMethodDiscreteSampler.java @@ -62,6 +62,15 @@ import java.util.Arrays; * <p>Larger table sizes that are a power of 2 will benefit from fast algorithms for * {@link UniformRandomProvider#nextInt(int)} that exploit the power of 2.</p> * + * <p><strong>Alias table size</strong></p> + * + * <p>Warning: There is no limit on the padding parameter. This allows the alias table to + * be configured to the desired size. Performance gains may show diminishing returns as + * the padding increases. This is dependent on the underlying probabilities of the + * enumerated distribution; and whether the table size is a power of 2 less than 2<sup>11</sup>. + * Users are advised to limit padding to bound the memory allocation unless benchmarking of + * the use case shows noticeable performance gains with a larger alias table.</p> + * * @see <a href="https://en.wikipedia.org/wiki/Alias_method";>Alias Method</a> * @see <a href="https://www.keithschwarz.com/darts-dice-coins/";>Darts, Dice, and Coins: * Sampling from a Discrete Distribution by Keith Schwartz</a> diff --git a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GuideTableDiscreteSampler.java b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GuideTableDiscreteSampler.java index d5002ade..f943b8a8 100644 --- a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GuideTableDiscreteSampler.java +++ b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/distribution/GuideTableDiscreteSampler.java @@ -30,8 +30,17 @@ import org.apache.commons.rng.UniformRandomProvider; * New York: Springer-Verlag. Chapter 3.2.4 "The method of guide tables" p. 96. * </blockquote> * - * <p>The size of the guide table can be controlled using a parameter. A larger guide table - * will improve performance at the cost of storage space.</p> + * <p><strong>Guide table size</strong></p> + * + * <p>The size of the guide table can be controlled using a scaling {@code alpha} parameter. + * A larger guide table will improve performance at the cost of storage space.</p> + * + * <p>Warning: There is no limit on the scaling parameter. This allows the guide table to + * be configured to the desired size. Performance gains may show diminishing returns as + * the scaling increases. This is dependent on the underlying probabilities of the + * enumerated distribution. Users are advised to limit scaling to bound the memory + * allocation unless benchmarking of the use case shows noticeable performance gains with + * a larger guide table.</p> * * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p> * diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 6f018ede..591e7e54 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -56,6 +56,11 @@ If the output is not quite correct, check for invisible trailing spaces! <release version="1.8" date="TBD" description=" New features, updates and bug fixes (requires Java 8). "> + <action dev="aherbert" type="update" due-to="Security scan, Alex Herbert" issue="RNG-202"> + "AliasMethodDiscreteSampler" and "GuideTableDiscreteSampler": Improve + documentation of the effects of the scaling factor on the internal table + size. + </action> <action dev="aherbert" type="update" due-to="Alex Herbert"> "GuideTableDiscreteSampler": Validate alpha is finite. </action>
