    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    }