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