Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Removed reference to deprecated class. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1540802 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Phil Steitz 2013-11-11 18:51:38 +00:00
parent 7cff45f1d7
commit 5df86e5cb2
1 changed files with 25 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
src/site/xdoc/userguide/random.xml
View File

@ -68,8 +68,8 @@
<subsection name="2.2 Random numbers" href="deviates">
<p>
The <a href="../apidocs/org/apache/commons/math3/random/RandomData.html">
RandomData</a> interface defines methods for generating random sequences
The <a href="../apidocs/org/apache/commons/math3/random/RandomDataGenerator.html">
RandomDataGenerator</a> class implements methods for generating random sequences
of numbers. The API contracts of these methods use the following concepts:
<dl>
<dt>Random sequence of numbers from a probability distribution</dt>
@ -90,8 +90,8 @@
<a href="../apidocs/org/apache/commons/math3/distribution/package-summary.html">
distributions</a> package.
The javadoc for the <code>nextXxx</code> methods in
<a href="../apidocs/org/apache/commons/math3/random/RandomDataImpl.html">
RandomDataImpl</a> describes the algorithms used to generate
<a href="../apidocs/org/apache/commons/math3/random/RandomDataGenerator.html">
RandomDataGenerator</a> describes the algorithms used to generate
random deviates.
</dd>
<dt>Cryptographically secure random sequences</dt>
@ -101,33 +101,32 @@
required, it is best to use a
<a href="http://www.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
secure random number generator</a> to generate values (or strings). The
nextSecureXxx methods in the <code>RandomDataImpl</code> implementation of
the <code>RandomData</code> interface use the JDK <code>SecureRandom</code>
PRNG to generate cryptographically secure sequences. The
<code>setSecureAlgorithm</code> method allows you to change the underlying
PRNG. These methods are <strong>much slower</strong> than the corresponding
"non-secure" versions, so they should only be used when cryptographic
nextSecureXxx methods implemented by <code>RandomDataGenerator</code>
use the JDK <code>SecureRandom</code> PRNG to generate cryptographically
secure sequences. The <code>setSecureAlgorithm</code> method allows you to
change the underlying PRNG. These methods are <strong>much slower</strong> than
the corresponding "non-secure" versions, so they should only be used when cryptographic
security is required. The <code>ISAACRandom</code> class implements a fast
cryptographically secure pseudorandom numbers generator.</dd>
cryptographically secure pseudorandom number generator.</dd>
<dt>Seeding pseudo-random number generators</dt>
<dd>By default, the implementation provided in <code>RandomDataImpl</code>
<dd>By default, the implementation provided in <code>RandomDataGenerator</code>
uses the JDK-provided PRNG. Like most other PRNGs, the JDK generator
generates sequences of random numbers based on an initial "seed value".
generates sequences of random numbers based on an initial "seed value."
For the non-secure methods, starting with the same seed always produces the
same sequence of values. Secure sequences started with the same seeds will
diverge. When a new <code>RandomDataImpl</code> is created, the underlying
diverge. When a new <code>RandomDataGenerator</code> is created, the underlying
random number generators are <strong>not</strong> initialized. The first
call to a data generation method, or to a <code>reSeed()</code> method
call to a data generation method, or to a <code>reSeed()</code> method
initializes the appropriate generator. If you do not explicitly seed the
generator, it is by default seeded with the current time in milliseconds.
Therefore, to generate sequences of random data values, you should always
instantiate <strong>one</strong> <code> RandomDataImpl</code> and use it
instantiate <strong>one</strong> <code> RandomDataGenerator</code> and use it
repeatedly instead of creating new instances for subsequent values in the
sequence. For example, the following will generate a random sequence of 50
long integers between 1 and 1,000,000, using the current time in
milliseconds as the seed for the JDK PRNG:
<source>
RandomData randomData = new RandomDataImpl();
RandomDataGenerator randomData = new RandomDataGenerator();
for (int i = 0; i &lt; 1000; i++) {
value = randomData.nextLong(1, 1000000);
}
@ -137,14 +136,14 @@ for (int i = 0; i &lt; 1000; i++) {
milliseconds:
<source>
for (int i = 0; i &lt; 1000; i++) {
RandomDataImpl randomData = new RandomDataImpl();
RandomDataGenerator randomData = new RandomDataGenerator();
value = randomData.nextLong(1, 1000000);
}
</source>
The following will produce the same random sequence each time it is
executed:
<source>
RandomData randomData = new RandomDataImpl();
RandomDataGenerator randomData = new RandomDataGenerator();
randomData.reSeed(1000);
for (int i = 0; i = 1000; i++) {
value = randomData.nextLong(1, 1000000);
@ -153,7 +152,7 @@ for (int i = 0; i = 1000; i++) {
The following will produce a different random sequence each time it is
executed.
<source>
RandomData randomData = new RandomDataImpl();
RandomDataGenerator randomData = new RandomDataGenerator();
randomData.reSeedSecure(1000);
for (int i = 0; i &lt; 1000; i++) {
value = randomData.nextSecureLong(1, 1000000);
@ -262,12 +261,12 @@ double[] randomVector = generator.nextVector();
of these methods produce sequences of strings with good dispersion
properties. The difference between the two methods is that the second is
cryptographically secure. Specifically, the implementation of
<code>nextHexString(n)</code> in <code>RandomDataImpl</code> uses the
<code>nextHexString(n)</code> in <code>RandomDataGenerator</code> uses the
following simple algorithm to generate a string of <code>n</code> hex digits:
<ol>
<li>n/2+1 binary bytes are generated using the underlying Random</li>
<li>n/2+1 binary bytes are generated using the underlying RandomGenerator</li>
<li>Each binary byte is translated into 2 hex digits</li></ol>
The <code>RandomDataImpl</code> implementation of the "secure" version,
The <code>RandomDataGenerator</code> implementation of the "secure" version,
<code>nextSecureHexString</code> generates hex characters in 40-byte
"chunks" using a 3-step process:
<ol>
@ -289,10 +288,10 @@ double[] randomVector = generator.nextVector();
href="combinatorics">
<p>
To select a random sample of objects in a collection, you can use the
<code>nextSample</code> method in the <code>RandomData</code> interface.
<code>nextSample</code> method implemented by <code>RandomDataGenerator</code>.
Specifically, if <code>c</code> is a collection containing at least
<code>k</code> objects, and <code>randomData</code> is a
<code>RandomData</code> instance <code>randomData.nextSample(c, k)</code>
<code>RandomDataGenerator</code> instance <code>randomData.nextSample(c, k)</code>
will return an <code>object[]</code> array of length <code>k</code>
consisting of elements randomly selected from the collection. If
<code>c</code> contains duplicate references, there may be duplicate
@ -300,7 +299,7 @@ double[] randomVector = generator.nextVector();
unique -- i.e., the sampling is without replacement among the object
references in the collection. </p>
<p>
If <code>randomData</code> is a <code>RandomData</code> instance, and
If <code>randomData</code> is a <code>RandomDataGenerator</code> instance, and
<code>n</code> and <code>k</code> are integers with
<code> k &lt;= n</code>, then
<code>randomData.nextPermutation(n, k)</code> returns an <code>int[]</code>