Apache/commons-math
1
0
Fork 0
mirror of https://github.com/apache/commons-math.git synced 2025-02-09 11:35:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Javadoc

Browse Source 
Made sure that exceptions are documented in both javadoc and method signatures.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1230906 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Sebastien Brisard 2012-01-13 07:04:10 +00:00
parent d61dba0cf6
commit ffbb85d329
2 changed files with 162 additions and 289 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
src/main/java/org/apache/commons/math/random/RandomData.java
View File

@ -18,188 +18,161 @@
package org.apache.commons.math.random; package org.apache.commons.math.random;
import java.util.Collection; import java.util.Collection;
import org.apache.commons.math.exception.NotStrictlyPositiveException;
import org.apache.commons.math.exception.NumberIsTooLargeException;
/** /**
* Random data generation utilities. * Random data generation utilities.
* @version $Id$ * @version $Id$
*/ */
public interface RandomData { public interface RandomData {
/** /**
* Generates a random string of hex characters of length * Generates a random string of hex characters of length {@code len}.
* <code>len</code>.
* <p> * <p>
* The generated string will be random, but not cryptographically * The generated string will be random, but not cryptographically
* secure. To generate cryptographically secure strings, use * secure. To generate cryptographically secure strings, use
* <code>nextSecureHexString</code></p> * {@link #nextSecureHexString(int)}.
* <p> * </p>
* <strong>Preconditions</strong>:<ul>
* <li><code>len > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* *
* @param len the length of the string to be generated * @param len the length of the string to be generated
* @return random string of hex characters of length <code>len</code> * @return a random string of hex characters of length {@code len}
* @throws NotStrictlyPositiveException if {@code len <= 0}
*/ */
String nextHexString(int len); String nextHexString(int len) throws NotStrictlyPositiveException;
/** /**
* Generates a uniformly distributed random integer between * Generates a uniformly distributed random integer between {@code lower}
* <code>lower</code> and <code>upper</code> (endpoints included). * and {@code upper} (endpoints included).
* <p> * <p>
* The generated integer will be random, but not cryptographically secure. * The generated integer will be random, but not cryptographically secure.
* To generate cryptographically secure integer sequences, use * To generate cryptographically secure integer sequences, use
* <code>nextSecureInt</code>.</p> * {@link #nextSecureInt(int, int)}.
* <p> * </p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* *
* @param lower lower bound for generated integer * @param lower lower bound for generated integer
* @param upper upper bound for generated integer * @param upper upper bound for generated integer
* @return a random integer greater than or equal to <code>lower</code> * @return a random integer greater than or equal to {@code lower}
* and less than or equal to <code>upper</code>. * and less than or equal to {@code upper}
* @throws NumberIsTooLargeException if {@code lower >= upper}
*/ */
int nextInt(int lower, int upper); int nextInt(int lower, int upper) throws NumberIsTooLargeException;
/** /**
* Generates a uniformly distributed random long integer between * Generates a uniformly distributed random long integer between
* <code>lower</code> and <code>upper</code> (endpoints included). * {@code lower} and {@code upper} (endpoints included).
* <p> * <p>
* The generated long integer values will be random, but not * The generated long integer values will be random, but not
* cryptographically secure. * cryptographically secure. To generate cryptographically secure sequences
* To generate cryptographically secure sequences of longs, use * of longs, use {@link #nextSecureLong(long, long)}.
* <code>nextSecureLong</code></p> * </p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* *
* @param lower lower bound for generated integer * @param lower lower bound for generated long integer
* @param upper upper bound for generated integer * @param upper upper bound for generated long integer
* @return a random integer greater than or equal to <code>lower</code> * @return a random long integer greater than or equal to {@code lower} and
* and less than or equal to <code>upper</code>. * less than or equal to {@code upper}
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/ */
long nextLong(long lower, long upper); long nextLong(long lower, long upper) throws NumberIsTooLargeException;
/** /**
* Generates a random string of hex characters from a secure random * Generates a random string of hex characters from a secure random
* sequence. * sequence.
* <p> * <p>
* If cryptographic security is not required, * If cryptographic security is not required, use
* use <code>nextHexString()</code>.</p> * {@link #nextHexString(int)}.
* <p> * </p>
* <strong>Preconditions</strong>:<ul> *
* <li><code>len > 0</code> (otherwise an IllegalArgumentException * @param len the length of the string to be generated
* is thrown.)</li> * @return a random string of hex characters of length {@code len}
* </ul></p> * @throws NotStrictlyPositiveException if {@code len <= 0}
* @param len length of return string
* @return the random hex string
*/ */
String nextSecureHexString(int len); String nextSecureHexString(int len) throws NotStrictlyPositiveException;
/** /**
* Generates a uniformly distributed random integer between * Generates a uniformly distributed random integer between {@code lower}
* <code>lower</code> and <code>upper</code> (endpoints included) * and {@code upper} (endpoints included) from a secure random sequence.
* from a secure random sequence.
* <p> * <p>
* Sequences of integers generated using this method will be * Sequences of integers generated using this method will be
* cryptographically secure. If cryptographic security is not required, * cryptographically secure. If cryptographic security is not required,
* <code>nextInt</code> should be used instead of this method.</p> * {@link #nextInt(int, int)} should be used instead of this method.</p>
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator"> * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
* Secure Random Sequence</a></p> * Secure Random Sequence</a></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* *
* @param lower lower bound for generated integer * @param lower lower bound for generated integer
* @param upper upper bound for generated integer * @param upper upper bound for generated integer
* @return a random integer greater than or equal to <code>lower</code> * @return a random integer greater than or equal to {@code lower} and less
* and less than or equal to <code>upper</code>. * than or equal to {@code upper}.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/ */
int nextSecureInt(int lower, int upper); int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException;
/** /**
* Generates a random long integer between <code>lower</code> * Generates a uniformly distributed random long integer between
* and <code>upper</code> (endpoints included). * {@code lower} and {@code upper} (endpoints included) from a secure random
* sequence.
* <p> * <p>
* Sequences of long values generated using this method will be * Sequences of long values generated using this method will be
* cryptographically secure. If cryptographic security is not required, * cryptographically secure. If cryptographic security is not required,
* <code>nextLong</code> should be used instead of this method.</p> * {@link #nextLong(long, long)} should be used instead of this method.</p>
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator"> * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
* Secure Random Sequence</a></p> * Secure Random Sequence</a></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul></p>
* *
* @param lower lower bound for generated integer * @param lower lower bound for generated integer
* @param upper upper bound for generated integer * @param upper upper bound for generated integer
* @return a long integer greater than or equal to <code>lower</code> * @return a random long integer greater than or equal to {@code lower} and
* and less than or equal to <code>upper</code>. * less than or equal to {@code upper}.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/ */
long nextSecureLong(long lower, long upper); long nextSecureLong(long lower, long upper)
throws NumberIsTooLargeException;
/** /**
* Generates a random value from the Poisson distribution with * Generates a random value from the Poisson distribution with the given
* the given mean. * mean.
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm"> * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
* Poisson Distribution</a></p> * Poisson Distribution</a></p>
* <p> *
* <strong>Preconditions</strong>: <ul> * @param mean the mean of the Poisson distribution
* <li>The specified mean <i>must</i> be positive (otherwise an * @return a random value following the specified Poisson distribution
* IllegalArgumentException is thrown.)</li> * @throws NotStrictlyPositiveException if {@code mean <= 0}.
* </ul></p>
* @param mean Mean of the distribution
* @return poisson deviate with the specified mean
*/ */
long nextPoisson(double mean); long nextPoisson(double mean) throws NotStrictlyPositiveException;
/** /**
* Generates a random value from the * Generates a random value from the Normal (or Gaussian) distribution with
* Normal (or Gaussian) distribution with the given mean * specified mean and standard deviation.
* and standard deviation.
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm"> * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
* Normal Distribution</a></p> * Normal Distribution</a></p>
* <p> *
* <strong>Preconditions</strong>: <ul> * @param mu the mean of the distribution
* <li><code>sigma > 0</code> (otherwise an IllegalArgumentException * @param sigma the standard deviation of the distribution
* is thrown.)</li> * @return a random value following the specified Gaussian distribution
* </ul></p> * @throws NotStrictlyPositiveException if {@code sigma <= 0}.
* @param mu Mean of the distribution
* @param sigma Standard deviation of the distribution
* @return random value from Gaussian distribution with mean = mu,
* standard deviation = sigma
*/ */
double nextGaussian(double mu, double sigma); double nextGaussian(double mu, double sigma)
throws NotStrictlyPositiveException;
/** /**
* Generates a random value from the exponential distribution * Generates a random value from the exponential distribution
* with expected value = <code>mean</code>. * with specified mean.
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm"> * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
* Exponential Distribution</a></p> * Exponential Distribution</a></p>
* <p> *
* <strong>Preconditions</strong>: <ul> * @param mean the mean of the distribution
* <li><code>mu >= 0</code> (otherwise an IllegalArgumentException * @return a random value following the specified exponential distribution
* is thrown.)</li> * @throws NotStrictlyPositiveException if {@code mean <= 0}.
* </ul></p>
* @param mean Mean of the distribution
* @return random value from exponential distribution
*/ */
double nextExponential(double mean); double nextExponential(double mean) throws NotStrictlyPositiveException;
/** /**
* Generates a uniformly distributed random value from the open interval * Generates a uniformly distributed random value from the open interval
@ -207,17 +180,18 @@ public interface RandomData {
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm"> * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
* Uniform Distribution</a> <code>lower</code> and * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
* <code>upper - lower</code> are the
* <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm"> * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
* location and scale parameters</a>, respectively.</p> * location and scale parameters</a>, respectively.</p>
* *
* @param lower lower endpoint of the interval of support * @param lower the exclusive lower bound of the support
* @param upper upper endpoint of the interval of support * @param upper the exclusive upper bound of the support
* @return uniformly distributed random value between lower * @return a uniformly distributed random value between lower and upper
* and upper (exclusive) * (exclusive)
* @throws NumberIsTooLargeException if {@code lower >= upper}
*/ */
double nextUniform(double lower, double upper); double nextUniform(double lower, double upper)
throws NumberIsTooLargeException;
/** /**
* Generates a uniformly distributed random value from the interval * Generates a uniformly distributed random value from the interval
@ -227,64 +201,56 @@ public interface RandomData {
* <p> * <p>
* <strong>Definition</strong>: * <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm"> * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
* Uniform Distribution</a> <code>lower</code> and * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
* <code>upper - lower</code> are the
* <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm"> * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
* location and scale parameters</a>, respectively.</p> * location and scale parameters</a>, respectively.</p>
* *
* @param lower lower endpoint of the interval of support * @param lower the lower bound of the support
* @param upper upper endpoint of the interval of support * @param upper the exclusive upper bound of the support
* @param lowerInclusive {@code true} if the lower bound is included in the * @param lowerInclusive {@code true} if the lower bound is inclusive
* interval
* @return uniformly distributed random value in the {@code (lower, upper)} * @return uniformly distributed random value in the {@code (lower, upper)}
* interval, if {@code lowerInclusive} is {@code false}, or in the * interval, if {@code lowerInclusive} is {@code false}, or in the
* {@code [lower, upper)} interval, if {@code lowerInclusive} is {@code true} * {@code [lower, upper)} interval, if {@code lowerInclusive} is {@code true}
* @throws NumberIsTooLargeException if {@code lower >= upper}
*/ */
double nextUniform(double lower, double upper, boolean lowerInclusive); double nextUniform(double lower, double upper, boolean lowerInclusive)
throws NumberIsTooLargeException;
/** /**
* Generates an integer array of length <code>k</code> whose entries * Generates an integer array of length {@code k} whose entries are selected
* are selected randomly, without repetition, from the integers <code> * randomly, without repetition, from the integers {@code 0, ..., n - 1}
* 0 through n-1</code> (inclusive). * (inclusive).
* <p> * <p>
* Generated arrays represent permutations * Generated arrays represent permutations of {@code n} taken {@code k} at a
* of <code>n</code> taken <code>k</code> at a time.</p> * time.</p>
* <p>
* <strong>Preconditions:</strong><ul>
* <li> <code>k <= n</code></li>
* <li> <code>n > 0</code> </li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is
* thrown.</p>
* *
* @param n domain of the permutation * @param n the domain of the permutation
* @param k size of the permutation * @param k the size of the permutation
* @return random k-permutation of n * @return a random {@code k}-permutation of {@code n}, as an array of
* integers
* @throws NumberIsTooLargeException if {@code k > n}.
* @throws NotStrictlyPositiveException if {@code k <= 0}.
*/ */
int[] nextPermutation(int n, int k); int[] nextPermutation(int n, int k)
throws NumberIsTooLargeException, NotStrictlyPositiveException;
/** /**
* Returns an array of <code>k</code> objects selected randomly * Returns an array of {@code k} objects selected randomly from the
* from the Collection <code>c</code>. * Collection {@code c}.
* <p> * <p>
* Sampling from <code>c</code> * Sampling from {@code c} is without replacement; but if {@code c} contains
* is without replacement; but if <code>c</code> contains identical * identical objects, the sample may include repeats. If all elements of
* objects, the sample may include repeats. If all elements of <code> * {@code c} are distinct, the resulting object array represents a
* c</code> are distinct, the resulting object array represents a
* <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000"> * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
* Simple Random Sample</a> of size * Simple Random Sample</a> of size {@code k} from the elements of
* <code>k</code> from the elements of <code>c</code>.</p> * {@code c}.</p>
* <p>
* <strong>Preconditions:</strong><ul>
* <li> k must be less than or equal to the size of c </li>
* <li> c must not be empty </li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is
* thrown.</p>
* *
* @param c collection to be sampled * @param c the collection to be sampled
* @param k size of the sample * @param k the size of the sample
* @return random sample of k elements from c * @return a random sample of {@code k} elements from {@code c}
* @throws NumberIsTooLargeException if {@code k > c.size()}.
* @throws NotStrictlyPositiveException if {@code k <= 0}.
*/ */
Object[] nextSample(Collection<?> c, int k); Object[] nextSample(Collection<?> c, int k)
throws NumberIsTooLargeException, NotStrictlyPositiveException;
} }

187
src/main/java/org/apache/commons/math/random/RandomDataImpl.java
View File

@ -187,19 +187,17 @@ public class RandomDataImpl implements RandomData, Serializable {
* <strong>Algorithm Description:</strong> hex strings are generated using a * <strong>Algorithm Description:</strong> hex strings are generated using a
* 2-step process. * 2-step process.
* <ol> * <ol>
* <li> * <li>{@code len / 2 + 1} binary bytes are generated using the underlying
* len/2+1 binary bytes are generated using the underlying Random</li> * Random</li>
* <li> * <li>Each binary byte is translated into 2 hex digits</li>
* Each binary byte is translated into 2 hex digits</li>
* </ol> * </ol>
* </p> * </p>
* *
* @param len * @param len the desired string length.
* the desired string length.
* @return the random string. * @return the random string.
* @throws NotStrictlyPositiveException if {@code len <= 0}. * @throws NotStrictlyPositiveException if {@code len <= 0}.
*/ */
public String nextHexString(int len) { public String nextHexString(int len) throws NotStrictlyPositiveException {
if (len <= 0) { if (len <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len); throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len);
} }
@ -234,38 +232,18 @@ public class RandomDataImpl implements RandomData, Serializable {
return outBuffer.toString().substring(0, len); return outBuffer.toString().substring(0, len);
} }
/** /** {@inheritDoc} */
* Generate a random int value uniformly distributed between public int nextInt(int lower, int upper) throws NumberIsTooLargeException {
* <code>lower</code> and <code>upper</code>, inclusive.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
public int nextInt(int lower, int upper) {
if (lower >= upper) { if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
lower, upper, false); lower, upper, false);
} }
double r = getRan().nextDouble(); double r = getRan().nextDouble();
double scaled = r * upper + (1.0 - r) * lower + r; double scaled = r * upper + (1.0 - r) * lower + r;
return (int)FastMath.floor(scaled); return (int) FastMath.floor(scaled);
} }
/** /** {@inheritDoc} */
* Generate a random long value uniformly distributed between
* <code>lower</code> and <code>upper</code>, inclusive.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
public long nextLong(long lower, long upper) { public long nextLong(long lower, long upper) {
if (lower >= upper) { if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
@ -291,13 +269,8 @@ public class RandomDataImpl implements RandomData, Serializable {
* Each byte of the binary digest is converted to 2 hex digits.</li> * Each byte of the binary digest is converted to 2 hex digits.</li>
* </ol> * </ol>
* </p> * </p>
*
* @param len
* the length of the generated string
* @return the random string
* @throws NotStrictlyPositiveException if {@code len <= 0}.
*/ */
public String nextSecureHexString(int len) { public String nextSecureHexString(int len) throws NotStrictlyPositiveException {
if (len <= 0) { if (len <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len); throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len);
} }
@ -323,7 +296,7 @@ public class RandomDataImpl implements RandomData, Serializable {
alg.update(randomBytes); alg.update(randomBytes);
// Compute hash -- will create 20-byte binary hash // Compute hash -- will create 20-byte binary hash
byte hash[] = alg.digest(); byte[] hash = alg.digest();
// Loop over the hash, converting each byte to 2 hex digits // Loop over the hash, converting each byte to 2 hex digits
for (int i = 0; i < hash.length; i++) { for (int i = 0; i < hash.length; i++) {
@ -346,18 +319,7 @@ public class RandomDataImpl implements RandomData, Serializable {
return outBuffer.toString().substring(0, len); return outBuffer.toString().substring(0, len);
} }
/** /** {@inheritDoc} */
* Generate a random int value uniformly distributed between
* <code>lower</code> and <code>upper</code>, inclusive. This algorithm uses
* a secure random number generator.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
public int nextSecureInt(int lower, int upper) { public int nextSecureInt(int lower, int upper) {
if (lower >= upper) { if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
@ -369,19 +331,10 @@ public class RandomDataImpl implements RandomData, Serializable {
return (int)FastMath.floor(scaled); return (int)FastMath.floor(scaled);
} }
/** /** {@inheritDoc} */
* Generate a random long value uniformly distributed between public long nextSecureLong(long lower, long upper)
* <code>lower</code> and <code>upper</code>, inclusive. This algorithm uses throws NumberIsTooLargeException {
* a secure random number generator.
*
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @return the random integer.
* @throws NumberIsTooLargeException if {@code lower >= upper}.
*/
public long nextSecureLong(long lower, long upper) {
if (lower >= upper) { if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
lower, upper, false); lower, upper, false);
@ -404,12 +357,8 @@ public class RandomDataImpl implements RandomData, Serializable {
* <li> For large means, uses the rejection algorithm described in <br/> * <li> For large means, uses the rejection algorithm described in <br/>
* Devroye, Luc. (1981).<i>The Computer Generation of Poisson Random Variables</i> * Devroye, Luc. (1981).<i>The Computer Generation of Poisson Random Variables</i>
* <strong>Computing</strong> vol. 26 pp. 197-207.</li></ul></p> * <strong>Computing</strong> vol. 26 pp. 197-207.</li></ul></p>
*
* @param mean mean of the Poisson distribution.
* @return the random Poisson value.
* @throws NotStrictlyPositiveException if {@code mean <= 0}.
*/ */
public long nextPoisson(double mean) { public long nextPoisson(double mean) throws NotStrictlyPositiveException {
if (mean <= 0) { if (mean <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.MEAN, mean); throw new NotStrictlyPositiveException(LocalizedFormats.MEAN, mean);
} }
@ -500,19 +449,10 @@ public class RandomDataImpl implements RandomData, Serializable {
} }
} }
/** /** {@inheritDoc} */
* Generate a random value from a Normal (a.k.a. Gaussian) distribution with public double nextGaussian(double mu, double sigma)
* the given mean, <code>mu</code> and the given standard deviation, throws NotStrictlyPositiveException {
* <code>sigma</code>.
*
* @param mu
* the mean of the distribution
* @param sigma
* the standard deviation of the distribution
* @return the random Normal value
* @throws NotStrictlyPositiveException if {@code sigma <= 0}.
*/
public double nextGaussian(double mu, double sigma) {
if (sigma <= 0) { if (sigma <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.STANDARD_DEVIATION, sigma); throw new NotStrictlyPositiveException(LocalizedFormats.STANDARD_DEVIATION, sigma);
} }
@ -520,8 +460,8 @@ public class RandomDataImpl implements RandomData, Serializable {
} }
/** /**
* Returns a random value from an Exponential distribution with the given * {@inheritDoc}
* mean. *
* <p> * <p>
* <strong>Algorithm Description</strong>: Uses the Algorithm SA (Ahrens) * <strong>Algorithm Description</strong>: Uses the Algorithm SA (Ahrens)
* from p. 876 in: * from p. 876 in:
@ -529,12 +469,10 @@ public class RandomDataImpl implements RandomData, Serializable {
* sampling from the exponential and normal distributions. * sampling from the exponential and normal distributions.
* Communications of the ACM, 15, 873-882. * Communications of the ACM, 15, 873-882.
* </p> * </p>
*
* @param mean the mean of the distribution
* @return the random Exponential value
* @throws NotStrictlyPositiveException if {@code mean <= 0}.
*/ */
public double nextExponential(double mean) { public double nextExponential(double mean)
throws NotStrictlyPositiveException {
if (mean <= 0.0) { if (mean <= 0.0) {
throw new NotStrictlyPositiveException(LocalizedFormats.MEAN, mean); throw new NotStrictlyPositiveException(LocalizedFormats.MEAN, mean);
} }
@ -579,6 +517,7 @@ public class RandomDataImpl implements RandomData, Serializable {
/** /**
* {@inheritDoc} * {@inheritDoc}
*
* <p> * <p>
* <strong>Algorithm Description</strong>: scales the output of * <strong>Algorithm Description</strong>: scales the output of
* Random.nextDouble(), but rejects 0 values (i.e., will generate another * Random.nextDouble(), but rejects 0 values (i.e., will generate another
@ -586,20 +525,18 @@ public class RandomDataImpl implements RandomData, Serializable {
* provide a symmetric output interval (both endpoints excluded). * provide a symmetric output interval (both endpoints excluded).
* </p> * </p>
* *
* @param lower the lower bound.
* @param upper the upper bound.
* @return a uniformly distributed random value from the interval (lower, upper)
* @throws NumberIsTooLargeException if {@code lower >= upper}
* @throws MathIllegalArgumentException if one of the bounds is infinite or * @throws MathIllegalArgumentException if one of the bounds is infinite or
* {@code NaN} * {@code NaN} or either bound is infinite or NaN
* or either bound is infinite or NaN
*/ */
public double nextUniform(double lower, double upper) { public double nextUniform(double lower, double upper)
throws NumberIsTooLargeException, MathIllegalArgumentException {
return nextUniform(lower, upper, false); return nextUniform(lower, upper, false);
} }
/** /**
* {@inheritDoc} * {@inheritDoc}
*
* <p> * <p>
* <strong>Algorithm Description</strong>: if the lower bound is excluded, * <strong>Algorithm Description</strong>: if the lower bound is excluded,
* scales the output of Random.nextDouble(), but rejects 0 values (i.e., * scales the output of Random.nextDouble(), but rejects 0 values (i.e.,
@ -608,20 +545,14 @@ public class RandomDataImpl implements RandomData, Serializable {
* endpoints excluded). * endpoints excluded).
* </p> * </p>
* *
* @param lower
* the lower bound.
* @param upper
* the upper bound.
* @param lowerInclusive
* whether the lower bound is included in the interval
* @return a uniformly distributed random value from the interval (lower,
* upper)
* @throws NumberIsTooLargeException if {@code lower >= upper}
* @throws MathIllegalArgumentException if one of the bounds is infinite or * @throws MathIllegalArgumentException if one of the bounds is infinite or
* {@code NaN} * {@code NaN}
* @since 3.0 * @since 3.0
*/ */
public double nextUniform(double lower, double upper, boolean lowerInclusive) { public double nextUniform(double lower, double upper,
boolean lowerInclusive)
throws NumberIsTooLargeException, MathIllegalArgumentException {
if (lower >= upper) { if (lower >= upper) {
throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, throw new NumberIsTooLargeException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
lower, upper, false); lower, upper, false);
@ -997,41 +928,20 @@ public class RandomDataImpl implements RandomData, Serializable {
} }
/** /**
* Generates an integer array of length <code>k</code> whose entries are * {@inheritDoc}
* selected randomly, without repetition, from the integers *
* <code>0 through n-1</code> (inclusive).
* <p>
* Generated arrays represent permutations of <code>n</code> taken
* <code>k</code> at a time.
* </p>
* <p>
* <strong>Preconditions:</strong>
* <ul>
* <li> <code>k <= n</code></li>
* <li> <code>n > 0</code></li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is thrown.
* </p>
* <p> * <p>
* Uses a 2-cycle permutation shuffle. The shuffling process is described <a * Uses a 2-cycle permutation shuffle. The shuffling process is described <a
* href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html"> * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
* here</a>. * here</a>.
* </p> * </p>
*
* @param n
* domain of the permutation (must be positive)
* @param k
* size of the permutation (must satisfy 0 < k <= n).
* @return the random permutation as an int array
* @throws NumberIsTooLargeException if {@code k > n}.
* @throws NotStrictlyPositiveException if {@code k <= 0}.
*/ */
public int[] nextPermutation(int n, int k) { public int[] nextPermutation(int n, int k) {
if (k > n) { if (k > n) {
throw new NumberIsTooLargeException(LocalizedFormats.PERMUTATION_EXCEEDS_N, throw new NumberIsTooLargeException(LocalizedFormats.PERMUTATION_EXCEEDS_N,
k, n, true); k, n, true);
} }
if (k == 0) { if (k <= 0) {
throw new NotStrictlyPositiveException(LocalizedFormats.PERMUTATION_SIZE, throw new NotStrictlyPositiveException(LocalizedFormats.PERMUTATION_SIZE,
k); k);
} }
@ -1047,24 +957,21 @@ public class RandomDataImpl implements RandomData, Serializable {
} }
/** /**
* Uses a 2-cycle permutation shuffle to generate a random permutation. * {@inheritDoc}
*
* <p>
* <strong>Algorithm Description</strong>: Uses a 2-cycle permutation * <strong>Algorithm Description</strong>: Uses a 2-cycle permutation
* shuffle to generate a random permutation of <code>c.size()</code> and * shuffle to generate a random permutation of <code>c.size()</code> and
* then returns the elements whose indexes correspond to the elements of the * then returns the elements whose indexes correspond to the elements of the
* generated permutation. This technique is described, and proven to * generated permutation. This technique is described, and proven to
* generate random samples, <a * generate random samples <a
* href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html"> * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
* here</a> * here</a>
* * </p>
* @param c
* Collection to sample from.
* @param k
* sample size.
* @return the random sample.
* @throws NumberIsTooLargeException if {@code k > c.size()}.
* @throws NotStrictlyPositiveException if {@code k <= 0}.
*/ */
public Object[] nextSample(Collection<?> c, int k) { public Object[] nextSample(Collection<?> c, int k)
throws NumberIsTooLargeException, NotStrictlyPositiveException {
int len = c.size(); int len = c.size();
if (k > len) { if (k > len) {
throw new NumberIsTooLargeException(LocalizedFormats.SAMPLE_SIZE_EXCEEDS_COLLECTION_SIZE, throw new NumberIsTooLargeException(LocalizedFormats.SAMPLE_SIZE_EXCEEDS_COLLECTION_SIZE,