commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From er...@apache.org
Subject [1/2] commons-rng git commit: Javadoc.
Date Sat, 27 Aug 2016 16:05:36 GMT
Repository: commons-rng
Updated Branches:
  refs/heads/master 5d8578185 -> 7d729fd78


Javadoc.


Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-rng/commit/90e2a7e5
Tree: http://git-wip-us.apache.org/repos/asf/commons-rng/tree/90e2a7e5
Diff: http://git-wip-us.apache.org/repos/asf/commons-rng/diff/90e2a7e5

Branch: refs/heads/master
Commit: 90e2a7e575642e9744ecbd06ec7bdaf748783406
Parents: 5d85781
Author: Gilles <erans@apache.org>
Authored: Sat Aug 27 19:27:05 2016 +0200
Committer: Gilles <erans@apache.org>
Committed: Sat Aug 27 19:27:05 2016 +0200

----------------------------------------------------------------------
 .../org/apache/commons/rng/RandomSource.java    | 36 +++++++++++++++-----
 1 file changed, 27 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/90e2a7e5/src/main/java/org/apache/commons/rng/RandomSource.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/rng/RandomSource.java b/src/main/java/org/apache/commons/rng/RandomSource.java
index eb318a1..18a58c1 100644
--- a/src/main/java/org/apache/commons/rng/RandomSource.java
+++ b/src/main/java/org/apache/commons/rng/RandomSource.java
@@ -85,6 +85,7 @@ import org.apache.commons.rng.internal.source64.TwoCmres;
  * by this library may <i>not</i> be the same as the sequences produced
  * by other implementations of the same algorithm!
  * </p>
+ *
  * <p>
  * For each algorithm, the Javadoc mentions the "ideal" size of the seed,
  * meaning the number of {@code int} or {@code long} values that is neither
@@ -94,21 +95,38 @@ import org.apache.commons.rng.internal.source64.TwoCmres;
  * </p>
  *
  * <p>
+ * Note that some algorithms are inherently sensitive to having too low
+ * diversity in their initial state.
+ * For example, it is often a bad idea to use a seed that is mostly
+ * composed of zeroes, or of repeated values.
+ * </p>
+ *
+ * <p>
  * This class provides methods to generate random seeds (single values
  * or arrays of values, of {@code int} or {@code long} types) that can
  * be passed to the {@link RandomSource#create(RandomSource,Object,Object[])
  * generators factory method}.
  * <br>
  * Although the seed-generating methods defined in this class will likely
- * return different values each time they are called, there is no guarantee
- * that the resulting "seed" will always generate a <i>good</i> (i.e.
- * sufficiently uniformly random for the intended purpose) sequence of
- * numbers, even if the generator is good!
- * The only way to ensure that the selected seed will make the generator
- * produce a good sequence is to submit that sequence to a series of
- * stringent tests, as provided by tools such as
- * <a href="http://www.phy.duke.edu/~rgb/General/dieharder.php">dieharder</a>
- * or <a href="http://simul.iro.umontreal.ca/testu01/tu01.html">TestU01</a>.
+ * return different values each time they are called, there is no guarantee:
+ * <ul>
+ *  <li>
+ *   In any sub-sequence, it is <a href="https://en.wikipedia.org/wiki/Birthday_problem">
+ *   expected</a> that the same numbers can occur, with a probability getting
+ *   higher as the range of allowed values is smaller and the sequence becomes
+ *   longer.
+ *  </li>
+ *  <li>
+ *   It possible that the resulting "seed" will not be <i>good</i> (i.e.
+ *   it will not generate a sufficiently uniformly random sequence for the
+ *   intended purpose), even if the generator is good!
+ *   The only way to ensure that the selected seed will make the generator
+ *   produce a good sequence is to submit that sequence to a series of
+ *   stringent tests, as provided by tools such as
+ *   <a href="http://www.phy.duke.edu/~rgb/General/dieharder.php">dieharder</a>
+ *   or <a href="http://simul.iro.umontreal.ca/testu01/tu01.html">TestU01</a>.
+ *  </li>
+ * </ul>
  * </p>
  *
  * <p>


Mime
View raw message