001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math3.random;
019
020 import java.io.Serializable;
021 import java.security.NoSuchAlgorithmException;
022 import java.security.NoSuchProviderException;
023 import java.util.Collection;
024
025 import org.apache.commons.math3.distribution.IntegerDistribution;
026 import org.apache.commons.math3.distribution.RealDistribution;
027 import org.apache.commons.math3.exception.NotANumberException;
028 import org.apache.commons.math3.exception.NotFiniteNumberException;
029 import org.apache.commons.math3.exception.NotPositiveException;
030 import org.apache.commons.math3.exception.NotStrictlyPositiveException;
031 import org.apache.commons.math3.exception.MathIllegalArgumentException;
032 import org.apache.commons.math3.exception.NumberIsTooLargeException;
033 import org.apache.commons.math3.exception.OutOfRangeException;
034
035 /**
036 * Generates random deviates and other random data using a {@link RandomGenerator}
037 * instance to generate non-secure data and a {@link java.security.SecureRandom}
038 * instance to provide data for the <code>nextSecureXxx</code> methods. If no
039 * <code>RandomGenerator</code> is provided in the constructor, the default is
040 * to use a {@link Well19937c} generator. To plug in a different
041 * implementation, either implement <code>RandomGenerator</code> directly or
042 * extend {@link AbstractRandomGenerator}.
043 * <p>
044 * Supports reseeding the underlying pseudo-random number generator (PRNG). The
045 * <code>SecurityProvider</code> and <code>Algorithm</code> used by the
046 * <code>SecureRandom</code> instance can also be reset.
047 * </p>
048 * <p>
049 * For details on the default PRNGs, see {@link java.util.Random} and
050 * {@link java.security.SecureRandom}.
051 * </p>
052 * <p>
053 * <strong>Usage Notes</strong>:
054 * <ul>
055 * <li>
056 * Instance variables are used to maintain <code>RandomGenerator</code> and
057 * <code>SecureRandom</code> instances used in data generation. Therefore, to
058 * generate a random sequence of values or strings, you should use just
059 * <strong>one</strong> <code>RandomDataGenerator</code> instance repeatedly.</li>
060 * <li>
061 * The "secure" methods are *much* slower. These should be used only when a
062 * cryptographically secure random sequence is required. A secure random
063 * sequence is a sequence of pseudo-random values which, in addition to being
064 * well-dispersed (so no subsequence of values is an any more likely than other
065 * subsequence of the the same length), also has the additional property that
066 * knowledge of values generated up to any point in the sequence does not make
067 * it any easier to predict subsequent values.</li>
068 * <li>
069 * When a new <code>RandomDataGenerator</code> is created, the underlying random
070 * number generators are <strong>not</strong> initialized. If you do not
071 * explicitly seed the default non-secure generator, it is seeded with the
072 * current time in milliseconds plus the system identity hash code on first use.
073 * The same holds for the secure generator. If you provide a <code>RandomGenerator</code>
074 * to the constructor, however, this generator is not reseeded by the constructor
075 * nor is it reseeded on first use.</li>
076 * <li>
077 * The <code>reSeed</code> and <code>reSeedSecure</code> methods delegate to the
078 * corresponding methods on the underlying <code>RandomGenerator</code> and
079 * <code>SecureRandom</code> instances. Therefore, <code>reSeed(long)</code>
080 * fully resets the initial state of the non-secure random number generator (so
081 * that reseeding with a specific value always results in the same subsequent
082 * random sequence); whereas reSeedSecure(long) does <strong>not</strong>
083 * reinitialize the secure random number generator (so secure sequences started
084 * with calls to reseedSecure(long) won't be identical).</li>
085 * <li>
086 * This implementation is not synchronized. The underlying <code>RandomGenerator</code>
087 * or <code>SecureRandom</code> instances are not protected by synchronization and
088 * are not guaranteed to be thread-safe. Therefore, if an instance of this class
089 * is concurrently utilized by multiple threads, it is the responsibility of
090 * client code to synchronize access to seeding and data generation methods.
091 * </li>
092 * </ul>
093 * </p>
094 * @deprecated to be removed in 4.0. Use {@link RandomDataGenerator} instead
095 * @version $Id: RandomDataImpl.java 1421917 2012-12-14 15:05:18Z erans $
096 */
097 @Deprecated
098 public class RandomDataImpl implements RandomData, Serializable {
099
100 /** Serializable version identifier */
101 private static final long serialVersionUID = -626730818244969716L;
102
103 /** RandomDataGenerator delegate */
104 private final RandomDataGenerator delegate;
105
106 /**
107 * Construct a RandomDataImpl, using a default random generator as the source
108 * of randomness.
109 *
110 * <p>The default generator is a {@link Well19937c} seeded
111 * with {@code System.currentTimeMillis() + System.identityHashCode(this))}.
112 * The generator is initialized and seeded on first use.</p>
113 */
114 public RandomDataImpl() {
115 delegate = new RandomDataGenerator();
116 }
117
118 /**
119 * Construct a RandomDataImpl using the supplied {@link RandomGenerator} as
120 * the source of (non-secure) random data.
121 *
122 * @param rand the source of (non-secure) random data
123 * (may be null, resulting in the default generator)
124 * @since 1.1
125 */
126 public RandomDataImpl(RandomGenerator rand) {
127 delegate = new RandomDataGenerator(rand);
128 }
129
130 /**
131 * @return the delegate object.
132 * @deprecated To be removed in 4.0.
133 */
134 @Deprecated
135 RandomDataGenerator getDelegate() {
136 return delegate;
137 }
138
139 /**
140 * {@inheritDoc}
141 * <p>
142 * <strong>Algorithm Description:</strong> hex strings are generated using a
143 * 2-step process.
144 * <ol>
145 * <li>{@code len / 2 + 1} binary bytes are generated using the underlying
146 * Random</li>
147 * <li>Each binary byte is translated into 2 hex digits</li>
148 * </ol>
149 * </p>
150 *
151 * @param len the desired string length.
152 * @return the random string.
153 * @throws NotStrictlyPositiveException if {@code len <= 0}.
154 */
155 public String nextHexString(int len) throws NotStrictlyPositiveException {
156 return delegate.nextHexString(len);
157 }
158
159 /** {@inheritDoc} */
160 public int nextInt(int lower, int upper) throws NumberIsTooLargeException {
161 return delegate.nextInt(lower, upper);
162 }
163
164 /** {@inheritDoc} */
165 public long nextLong(long lower, long upper) throws NumberIsTooLargeException {
166 return delegate.nextLong(lower, upper);
167 }
168
169 /**
170 * {@inheritDoc}
171 * <p>
172 * <strong>Algorithm Description:</strong> hex strings are generated in
173 * 40-byte segments using a 3-step process.
174 * <ol>
175 * <li>
176 * 20 random bytes are generated using the underlying
177 * <code>SecureRandom</code>.</li>
178 * <li>
179 * SHA-1 hash is applied to yield a 20-byte binary digest.</li>
180 * <li>
181 * Each byte of the binary digest is converted to 2 hex digits.</li>
182 * </ol>
183 * </p>
184 */
185 public String nextSecureHexString(int len) throws NotStrictlyPositiveException {
186 return delegate.nextSecureHexString(len);
187 }
188
189 /** {@inheritDoc} */
190 public int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException {
191 return delegate.nextSecureInt(lower, upper);
192 }
193
194 /** {@inheritDoc} */
195 public long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException {
196 return delegate.nextSecureLong(lower,upper);
197 }
198
199 /**
200 * {@inheritDoc}
201 * <p>
202 * <strong>Algorithm Description</strong>:
203 * <ul><li> For small means, uses simulation of a Poisson process
204 * using Uniform deviates, as described
205 * <a href="http://irmi.epfl.ch/cmos/Pmmi/interactive/rng7.htm"> here.</a>
206 * The Poisson process (and hence value returned) is bounded by 1000 * mean.</li>
207 *
208 * <li> For large means, uses the rejection algorithm described in <br/>
209 * Devroye, Luc. (1981).<i>The Computer Generation of Poisson Random Variables</i>
210 * <strong>Computing</strong> vol. 26 pp. 197-207.</li></ul></p>
211 */
212 public long nextPoisson(double mean) throws NotStrictlyPositiveException {
213 return delegate.nextPoisson(mean);
214 }
215
216 /** {@inheritDoc} */
217 public double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException {
218 return delegate.nextGaussian(mu,sigma);
219 }
220
221 /**
222 * {@inheritDoc}
223 *
224 * <p>
225 * <strong>Algorithm Description</strong>: Uses the Algorithm SA (Ahrens)
226 * from p. 876 in:
227 * [1]: Ahrens, J. H. and Dieter, U. (1972). Computer methods for
228 * sampling from the exponential and normal distributions.
229 * Communications of the ACM, 15, 873-882.
230 * </p>
231 */
232 public double nextExponential(double mean) throws NotStrictlyPositiveException {
233 return delegate.nextExponential(mean);
234 }
235
236 /**
237 * {@inheritDoc}
238 *
239 * <p>
240 * <strong>Algorithm Description</strong>: scales the output of
241 * Random.nextDouble(), but rejects 0 values (i.e., will generate another
242 * random double if Random.nextDouble() returns 0). This is necessary to
243 * provide a symmetric output interval (both endpoints excluded).
244 * </p>
245 */
246 public double nextUniform(double lower, double upper)
247 throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException {
248 return delegate.nextUniform(lower, upper);
249 }
250
251 /**
252 * {@inheritDoc}
253 *
254 * <p>
255 * <strong>Algorithm Description</strong>: if the lower bound is excluded,
256 * scales the output of Random.nextDouble(), but rejects 0 values (i.e.,
257 * will generate another random double if Random.nextDouble() returns 0).
258 * This is necessary to provide a symmetric output interval (both
259 * endpoints excluded).
260 * </p>
261 * @since 3.0
262 */
263 public double nextUniform(double lower, double upper, boolean lowerInclusive)
264 throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException {
265 return delegate.nextUniform(lower, upper, lowerInclusive);
266 }
267
268 /**
269 * Generates a random value from the {@link org.apache.commons.math3.distribution.BetaDistribution Beta Distribution}.
270 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
271 * to generate random values.
272 *
273 * @param alpha first distribution shape parameter
274 * @param beta second distribution shape parameter
275 * @return random value sampled from the beta(alpha, beta) distribution
276 * @since 2.2
277 */
278 public double nextBeta(double alpha, double beta) {
279 return delegate.nextBeta(alpha, beta);
280 }
281
282 /**
283 * Generates a random value from the {@link org.apache.commons.math3.distribution.BinomialDistribution Binomial Distribution}.
284 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
285 * to generate random values.
286 *
287 * @param numberOfTrials number of trials of the Binomial distribution
288 * @param probabilityOfSuccess probability of success of the Binomial distribution
289 * @return random value sampled from the Binomial(numberOfTrials, probabilityOfSuccess) distribution
290 * @since 2.2
291 */
292 public int nextBinomial(int numberOfTrials, double probabilityOfSuccess) {
293 return delegate.nextBinomial(numberOfTrials, probabilityOfSuccess);
294 }
295
296 /**
297 * Generates a random value from the {@link org.apache.commons.math3.distribution.CauchyDistribution Cauchy Distribution}.
298 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
299 * to generate random values.
300 *
301 * @param median the median of the Cauchy distribution
302 * @param scale the scale parameter of the Cauchy distribution
303 * @return random value sampled from the Cauchy(median, scale) distribution
304 * @since 2.2
305 */
306 public double nextCauchy(double median, double scale) {
307 return delegate.nextCauchy(median, scale);
308 }
309
310 /**
311 * Generates a random value from the {@link org.apache.commons.math3.distribution.ChiSquaredDistribution ChiSquare Distribution}.
312 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
313 * to generate random values.
314 *
315 * @param df the degrees of freedom of the ChiSquare distribution
316 * @return random value sampled from the ChiSquare(df) distribution
317 * @since 2.2
318 */
319 public double nextChiSquare(double df) {
320 return delegate.nextChiSquare(df);
321 }
322
323 /**
324 * Generates a random value from the {@link org.apache.commons.math3.distribution.FDistribution F Distribution}.
325 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
326 * to generate random values.
327 *
328 * @param numeratorDf the numerator degrees of freedom of the F distribution
329 * @param denominatorDf the denominator degrees of freedom of the F distribution
330 * @return random value sampled from the F(numeratorDf, denominatorDf) distribution
331 * @throws NotStrictlyPositiveException if
332 * {@code numeratorDf <= 0} or {@code denominatorDf <= 0}.
333 * @since 2.2
334 */
335 public double nextF(double numeratorDf, double denominatorDf) throws NotStrictlyPositiveException {
336 return delegate.nextF(numeratorDf, denominatorDf);
337 }
338
339 /**
340 * <p>Generates a random value from the
341 * {@link org.apache.commons.math3.distribution.GammaDistribution Gamma Distribution}.</p>
342 *
343 * <p>This implementation uses the following algorithms: </p>
344 *
345 * <p>For 0 < shape < 1: <br/>
346 * Ahrens, J. H. and Dieter, U., <i>Computer methods for
347 * sampling from gamma, beta, Poisson and binomial distributions.</i>
348 * Computing, 12, 223-246, 1974.</p>
349 *
350 * <p>For shape >= 1: <br/>
351 * Marsaglia and Tsang, <i>A Simple Method for Generating
352 * Gamma Variables.</i> ACM Transactions on Mathematical Software,
353 * Volume 26 Issue 3, September, 2000.</p>
354 *
355 * @param shape the median of the Gamma distribution
356 * @param scale the scale parameter of the Gamma distribution
357 * @return random value sampled from the Gamma(shape, scale) distribution
358 * @throws NotStrictlyPositiveException if {@code shape <= 0} or
359 * {@code scale <= 0}.
360 * @since 2.2
361 */
362 public double nextGamma(double shape, double scale) throws NotStrictlyPositiveException {
363 return delegate.nextGamma(shape, scale);
364 }
365
366 /**
367 * Generates a random value from the {@link org.apache.commons.math3.distribution.HypergeometricDistribution Hypergeometric Distribution}.
368 * This implementation uses {@link #nextInversionDeviate(IntegerDistribution) inversion}
369 * to generate random values.
370 *
371 * @param populationSize the population size of the Hypergeometric distribution
372 * @param numberOfSuccesses number of successes in the population of the Hypergeometric distribution
373 * @param sampleSize the sample size of the Hypergeometric distribution
374 * @return random value sampled from the Hypergeometric(numberOfSuccesses, sampleSize) distribution
375 * @throws NumberIsTooLargeException if {@code numberOfSuccesses > populationSize},
376 * or {@code sampleSize > populationSize}.
377 * @throws NotStrictlyPositiveException if {@code populationSize <= 0}.
378 * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
379 * @since 2.2
380 */
381 public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize)
382 throws NotPositiveException, NotStrictlyPositiveException, NumberIsTooLargeException {
383 return delegate.nextHypergeometric(populationSize, numberOfSuccesses, sampleSize);
384 }
385
386 /**
387 * Generates a random value from the {@link org.apache.commons.math3.distribution.PascalDistribution Pascal Distribution}.
388 * This implementation uses {@link #nextInversionDeviate(IntegerDistribution) inversion}
389 * to generate random values.
390 *
391 * @param r the number of successes of the Pascal distribution
392 * @param p the probability of success of the Pascal distribution
393 * @return random value sampled from the Pascal(r, p) distribution
394 * @since 2.2
395 * @throws NotStrictlyPositiveException if the number of successes is not positive
396 * @throws OutOfRangeException if the probability of success is not in the
397 * range {@code [0, 1]}.
398 */
399 public int nextPascal(int r, double p)
400 throws NotStrictlyPositiveException, OutOfRangeException {
401 return delegate.nextPascal(r, p);
402 }
403
404 /**
405 * Generates a random value from the {@link org.apache.commons.math3.distribution.TDistribution T Distribution}.
406 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
407 * to generate random values.
408 *
409 * @param df the degrees of freedom of the T distribution
410 * @return random value from the T(df) distribution
411 * @since 2.2
412 * @throws NotStrictlyPositiveException if {@code df <= 0}
413 */
414 public double nextT(double df) throws NotStrictlyPositiveException {
415 return delegate.nextT(df);
416 }
417
418 /**
419 * Generates a random value from the {@link org.apache.commons.math3.distribution.WeibullDistribution Weibull Distribution}.
420 * This implementation uses {@link #nextInversionDeviate(RealDistribution) inversion}
421 * to generate random values.
422 *
423 * @param shape the shape parameter of the Weibull distribution
424 * @param scale the scale parameter of the Weibull distribution
425 * @return random value sampled from the Weibull(shape, size) distribution
426 * @since 2.2
427 * @throws NotStrictlyPositiveException if {@code shape <= 0} or
428 * {@code scale <= 0}.
429 */
430 public double nextWeibull(double shape, double scale) throws NotStrictlyPositiveException {
431 return delegate.nextWeibull(shape, scale);
432 }
433
434 /**
435 * Generates a random value from the {@link org.apache.commons.math3.distribution.ZipfDistribution Zipf Distribution}.
436 * This implementation uses {@link #nextInversionDeviate(IntegerDistribution) inversion}
437 * to generate random values.
438 *
439 * @param numberOfElements the number of elements of the ZipfDistribution
440 * @param exponent the exponent of the ZipfDistribution
441 * @return random value sampled from the Zipf(numberOfElements, exponent) distribution
442 * @since 2.2
443 * @exception NotStrictlyPositiveException if {@code numberOfElements <= 0}
444 * or {@code exponent <= 0}.
445 */
446 public int nextZipf(int numberOfElements, double exponent) throws NotStrictlyPositiveException {
447 return delegate.nextZipf(numberOfElements, exponent);
448 }
449
450
451 /**
452 * Reseeds the random number generator with the supplied seed.
453 * <p>
454 * Will create and initialize if null.
455 * </p>
456 *
457 * @param seed
458 * the seed value to use
459 */
460 public void reSeed(long seed) {
461 delegate.reSeed(seed);
462 }
463
464 /**
465 * Reseeds the secure random number generator with the current time in
466 * milliseconds.
467 * <p>
468 * Will create and initialize if null.
469 * </p>
470 */
471 public void reSeedSecure() {
472 delegate.reSeedSecure();
473 }
474
475 /**
476 * Reseeds the secure random number generator with the supplied seed.
477 * <p>
478 * Will create and initialize if null.
479 * </p>
480 *
481 * @param seed
482 * the seed value to use
483 */
484 public void reSeedSecure(long seed) {
485 delegate.reSeedSecure(seed);
486 }
487
488 /**
489 * Reseeds the random number generator with
490 * {@code System.currentTimeMillis() + System.identityHashCode(this))}.
491 */
492 public void reSeed() {
493 delegate.reSeed();
494 }
495
496 /**
497 * Sets the PRNG algorithm for the underlying SecureRandom instance using
498 * the Security Provider API. The Security Provider API is defined in <a
499 * href =
500 * "http://java.sun.com/j2se/1.3/docs/guide/security/CryptoSpec.html#AppA">
501 * Java Cryptography Architecture API Specification & Reference.</a>
502 * <p>
503 * <strong>USAGE NOTE:</strong> This method carries <i>significant</i>
504 * overhead and may take several seconds to execute.
505 * </p>
506 *
507 * @param algorithm
508 * the name of the PRNG algorithm
509 * @param provider
510 * the name of the provider
511 * @throws NoSuchAlgorithmException
512 * if the specified algorithm is not available
513 * @throws NoSuchProviderException
514 * if the specified provider is not installed
515 */
516 public void setSecureAlgorithm(String algorithm, String provider)
517 throws NoSuchAlgorithmException, NoSuchProviderException {
518 delegate.setSecureAlgorithm(algorithm, provider);
519 }
520
521 /**
522 * {@inheritDoc}
523 *
524 * <p>
525 * Uses a 2-cycle permutation shuffle. The shuffling process is described <a
526 * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
527 * here</a>.
528 * </p>
529 */
530 public int[] nextPermutation(int n, int k)
531 throws NotStrictlyPositiveException, NumberIsTooLargeException {
532 return delegate.nextPermutation(n, k);
533 }
534
535 /**
536 * {@inheritDoc}
537 *
538 * <p>
539 * <strong>Algorithm Description</strong>: Uses a 2-cycle permutation
540 * shuffle to generate a random permutation of <code>c.size()</code> and
541 * then returns the elements whose indexes correspond to the elements of the
542 * generated permutation. This technique is described, and proven to
543 * generate random samples <a
544 * href="http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node83.html">
545 * here</a>
546 * </p>
547 */
548 public Object[] nextSample(Collection<?> c, int k)
549 throws NotStrictlyPositiveException, NumberIsTooLargeException {
550 return delegate.nextSample(c, k);
551 }
552
553 /**
554 * Generate a random deviate from the given distribution using the
555 * <a href="http://en.wikipedia.org/wiki/Inverse_transform_sampling"> inversion method.</a>
556 *
557 * @param distribution Continuous distribution to generate a random value from
558 * @return a random value sampled from the given distribution
559 * @throws MathIllegalArgumentException if the underlynig distribution throws one
560 * @since 2.2
561 * @deprecated use the distribution's sample() method
562 */
563 public double nextInversionDeviate(RealDistribution distribution)
564 throws MathIllegalArgumentException {
565 return distribution.inverseCumulativeProbability(nextUniform(0, 1));
566
567 }
568
569 /**
570 * Generate a random deviate from the given distribution using the
571 * <a href="http://en.wikipedia.org/wiki/Inverse_transform_sampling"> inversion method.</a>
572 *
573 * @param distribution Integer distribution to generate a random value from
574 * @return a random value sampled from the given distribution
575 * @throws MathIllegalArgumentException if the underlynig distribution throws one
576 * @since 2.2
577 * @deprecated use the distribution's sample() method
578 */
579 public int nextInversionDeviate(IntegerDistribution distribution)
580 throws MathIllegalArgumentException {
581 return distribution.inverseCumulativeProbability(nextUniform(0, 1));
582 }
583
584 }