path: root/src/main/java/org/apache/commons/math3/random/RandomDataGenerator.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.math3.random;

import org.apache.commons.math3.distribution.BetaDistribution;
import org.apache.commons.math3.distribution.BinomialDistribution;
import org.apache.commons.math3.distribution.CauchyDistribution;
import org.apache.commons.math3.distribution.ChiSquaredDistribution;
import org.apache.commons.math3.distribution.ExponentialDistribution;
import org.apache.commons.math3.distribution.FDistribution;
import org.apache.commons.math3.distribution.GammaDistribution;
import org.apache.commons.math3.distribution.HypergeometricDistribution;
import org.apache.commons.math3.distribution.PascalDistribution;
import org.apache.commons.math3.distribution.PoissonDistribution;
import org.apache.commons.math3.distribution.TDistribution;
import org.apache.commons.math3.distribution.UniformIntegerDistribution;
import org.apache.commons.math3.distribution.WeibullDistribution;
import org.apache.commons.math3.distribution.ZipfDistribution;
import org.apache.commons.math3.exception.MathInternalError;
import org.apache.commons.math3.exception.NotANumberException;
import org.apache.commons.math3.exception.NotFiniteNumberException;
import org.apache.commons.math3.exception.NotPositiveException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NumberIsTooLargeException;
import org.apache.commons.math3.exception.OutOfRangeException;
import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.util.MathArrays;

import java.io.Serializable;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.NoSuchProviderException;
import java.security.SecureRandom;
import java.util.Collection;

/**
 * Implements the {@link RandomData} interface using a {@link RandomGenerator} instance to generate
 * non-secure data and a {@link java.security.SecureRandom} instance to provide data for the <code>
 * nextSecureXxx</code> methods. If no <code>RandomGenerator</code> is provided in the constructor,
 * the default is to use a {@link Well19937c} generator. To plug in a different implementation,
 * either implement <code>RandomGenerator</code> directly or extend {@link AbstractRandomGenerator}.
 *
 * <p>Supports reseeding the underlying pseudo-random number generator (PRNG). The <code>
 * SecurityProvider</code> and <code>Algorithm</code> used by the <code>SecureRandom</code> instance
 * can also be reset.
 *
 * <p>For details on the default PRNGs, see {@link java.util.Random} and {@link
 * java.security.SecureRandom}.
 *
 * <p><strong>Usage Notes</strong>:
 *
 * <ul>
 *   <li>Instance variables are used to maintain <code>RandomGenerator</code> and <code>SecureRandom
 *       </code> instances used in data generation. Therefore, to generate a random sequence of
 *       values or strings, you should use just <strong>one</strong> <code>RandomDataImpl</code>
 *       instance repeatedly.
 *   <li>The "secure" methods are *much* slower. These should be used only when a cryptographically
 *       secure random sequence is required. A secure random sequence is a sequence of pseudo-random
 *       values which, in addition to being well-dispersed (so no subsequence of values is an any
 *       more likely than other subsequence of the the same length), also has the additional
 *       property that knowledge of values generated up to any point in the sequence does not make
 *       it any easier to predict subsequent values.
 *   <li>When a new <code>RandomDataImpl</code> is created, the underlying random number generators
 *       are <strong>not</strong> initialized. If you do not explicitly seed the default non-secure
 *       generator, it is seeded with the current time in milliseconds plus the system identity hash
 *       code on first use. The same holds for the secure generator. If you provide a <code>
 *       RandomGenerator</code> to the constructor, however, this generator is not reseeded by the
 *       constructor nor is it reseeded on first use.
 *   <li>The <code>reSeed</code> and <code>reSeedSecure</code> methods delegate to the corresponding
 *       methods on the underlying <code>RandomGenerator</code> and <code>SecureRandom</code>
 *       instances. Therefore, <code>reSeed(long)</code> fully resets the initial state of the
 *       non-secure random number generator (so that reseeding with a specific value always results
 *       in the same subsequent random sequence); whereas reSeedSecure(long) does
 *       <strong>not</strong> reinitialize the secure random number generator (so secure sequences
 *       started with calls to reseedSecure(long) won't be identical).
 *   <li>This implementation is not synchronized. The underlying <code>RandomGenerator</code> or
 *       <code>SecureRandom</code> instances are not protected by synchronization and are not
 *       guaranteed to be thread-safe. Therefore, if an instance of this class is concurrently
 *       utilized by multiple threads, it is the responsibility of client code to synchronize access
 *       to seeding and data generation methods.
 * </ul>
 *
 * @since 3.1
 */
public class RandomDataGenerator implements RandomData, Serializable {

    /** Serializable version identifier */
    private static final long serialVersionUID = -626730818244969716L;

    /** underlying random number generator */
    private RandomGenerator rand = null;

    /** underlying secure random number generator */
    private RandomGenerator secRand = null;

    /**
     * Construct a RandomDataGenerator, using a default random generator as the source of
     * randomness.
     *
     * <p>The default generator is a {@link Well19937c} seeded with {@code
     * System.currentTimeMillis() + System.identityHashCode(this))}. The generator is initialized
     * and seeded on first use.
     */
    public RandomDataGenerator() {}

    /**
     * Construct a RandomDataGenerator using the supplied {@link RandomGenerator} as the source of
     * (non-secure) random data.
     *
     * @param rand the source of (non-secure) random data (may be null, resulting in the default
     *     generator)
     */
    public RandomDataGenerator(RandomGenerator rand) {
        this.rand = rand;
    }

    /**
     * {@inheritDoc}
     *
     * <p><strong>Algorithm Description:</strong> hex strings are generated using a 2-step process.
     *
     * <ol>
     *   <li>{@code len / 2 + 1} binary bytes are generated using the underlying Random
     *   <li>Each binary byte is translated into 2 hex digits
     * </ol>
     *
     * @param len the desired string length.
     * @return the random string.
     * @throws NotStrictlyPositiveException if {@code len <= 0}.
     */
    public String nextHexString(int len) throws NotStrictlyPositiveException {
        if (len <= 0) {
            throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len);
        }

        // Get a random number generator
        RandomGenerator ran = getRandomGenerator();

        // Initialize output buffer
        StringBuilder outBuffer = new StringBuilder();

        // Get int(len/2)+1 random bytes
        byte[] randomBytes = new byte[(len / 2) + 1];
        ran.nextBytes(randomBytes);

        // Convert each byte to 2 hex digits
        for (int i = 0; i < randomBytes.length; i++) {
            Integer c = Integer.valueOf(randomBytes[i]);

            /*
             * Add 128 to byte value to make interval 0-255 before doing hex
             * conversion. This guarantees <= 2 hex digits from toHexString()
             * toHexString would otherwise add 2^32 to negative arguments.
             */
            String hex = Integer.toHexString(c.intValue() + 128);

            // Make sure we add 2 hex digits for each byte
            if (hex.length() == 1) {
                hex = "0" + hex;
            }
            outBuffer.append(hex);
        }
        return outBuffer.toString().substring(0, len);
    }

    /** {@inheritDoc} */
    public int nextInt(final int lower, final int upper) throws NumberIsTooLargeException {
        return new UniformIntegerDistribution(getRandomGenerator(), lower, upper).sample();
    }

    /** {@inheritDoc} */
    public long nextLong(final long lower, final long upper) throws NumberIsTooLargeException {
        if (lower >= upper) {
            throw new NumberIsTooLargeException(
                    LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false);
        }
        final long max = (upper - lower) + 1;
        if (max <= 0) {
            // the range is too wide to fit in a positive long (larger than 2^63); as it covers
            // more than half the long range, we use directly a simple rejection method
            final RandomGenerator rng = getRandomGenerator();
            while (true) {
                final long r = rng.nextLong();
                if (r >= lower && r <= upper) {
                    return r;
                }
            }
        } else if (max < Integer.MAX_VALUE) {
            // we can shift the range and generate directly a positive int
            return lower + getRandomGenerator().nextInt((int) max);
        } else {
            // we can shift the range and generate directly a positive long
            return lower + nextLong(getRandomGenerator(), max);
        }
    }

    /**
     * Returns a pseudorandom, uniformly distributed {@code long} value between 0 (inclusive) and
     * the specified value (exclusive), drawn from this random number generator's sequence.
     *
     * @param rng random generator to use
     * @param n the bound on the random number to be returned. Must be positive.
     * @return a pseudorandom, uniformly distributed {@code long} value between 0 (inclusive) and n
     *     (exclusive).
     * @throws IllegalArgumentException if n is not positive.
     */
    private static long nextLong(final RandomGenerator rng, final long n)
            throws IllegalArgumentException {
        if (n > 0) {
            final byte[] byteArray = new byte[8];
            long bits;
            long val;
            do {
                rng.nextBytes(byteArray);
                bits = 0;
                for (final byte b : byteArray) {
                    bits = (bits << 8) | (((long) b) & 0xffL);
                }
                bits &= 0x7fffffffffffffffL;
                val = bits % n;
            } while (bits - val + (n - 1) < 0);
            return val;
        }
        throw new NotStrictlyPositiveException(n);
    }

    /**
     * {@inheritDoc}
     *
     * <p><strong>Algorithm Description:</strong> hex strings are generated in 40-byte segments
     * using a 3-step process.
     *
     * <ol>
     *   <li>20 random bytes are generated using the underlying <code>SecureRandom</code>.
     *   <li>SHA-1 hash is applied to yield a 20-byte binary digest.
     *   <li>Each byte of the binary digest is converted to 2 hex digits.
     * </ol>
     *
     * @throws NotStrictlyPositiveException if {@code len <= 0}
     */
    public String nextSecureHexString(int len) throws NotStrictlyPositiveException {
        if (len <= 0) {
            throw new NotStrictlyPositiveException(LocalizedFormats.LENGTH, len);
        }

        // Get SecureRandom and setup Digest provider
        final RandomGenerator secRan = getSecRan();
        MessageDigest alg = null;
        try {
            alg = MessageDigest.getInstance("SHA-1");
        } catch (NoSuchAlgorithmException ex) {
            // this should never happen
            throw new MathInternalError(ex);
        }
        alg.reset();

        // Compute number of iterations required (40 bytes each)
        int numIter = (len / 40) + 1;

        StringBuilder outBuffer = new StringBuilder();
        for (int iter = 1; iter < numIter + 1; iter++) {
            byte[] randomBytes = new byte[40];
            secRan.nextBytes(randomBytes);
            alg.update(randomBytes);

            // Compute hash -- will create 20-byte binary hash
            byte[] hash = alg.digest();

            // Loop over the hash, converting each byte to 2 hex digits
            for (int i = 0; i < hash.length; i++) {
                Integer c = Integer.valueOf(hash[i]);

                /*
                 * Add 128 to byte value to make interval 0-255 This guarantees
                 * <= 2 hex digits from toHexString() toHexString would
                 * otherwise add 2^32 to negative arguments
                 */
                String hex = Integer.toHexString(c.intValue() + 128);

                // Keep strings uniform length -- guarantees 40 bytes
                if (hex.length() == 1) {
                    hex = "0" + hex;
                }
                outBuffer.append(hex);
            }
        }
        return outBuffer.toString().substring(0, len);
    }

    /** {@inheritDoc} */
    public int nextSecureInt(final int lower, final int upper) throws NumberIsTooLargeException {
        return new UniformIntegerDistribution(getSecRan(), lower, upper).sample();
    }

    /** {@inheritDoc} */
    public long nextSecureLong(final long lower, final long upper)
            throws NumberIsTooLargeException {
        if (lower >= upper) {
            throw new NumberIsTooLargeException(
                    LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false);
        }
        final RandomGenerator rng = getSecRan();
        final long max = (upper - lower) + 1;
        if (max <= 0) {
            // the range is too wide to fit in a positive long (larger than 2^63); as it covers
            // more than half the long range, we use directly a simple rejection method
            while (true) {
                final long r = rng.nextLong();
                if (r >= lower && r <= upper) {
                    return r;
                }
            }
        } else if (max < Integer.MAX_VALUE) {
            // we can shift the range and generate directly a positive int
            return lower + rng.nextInt((int) max);
        } else {
            // we can shift the range and generate directly a positive long
            return lower + nextLong(rng, max);
        }
    }

    /**
     * {@inheritDoc}
     *
     * <p><strong>Algorithm Description</strong>:
     *
     * <ul>
     *   <li>For small means, uses simulation of a Poisson process using Uniform deviates, as
     *       described <a href="http://irmi.epfl.ch/cmos/Pmmi/interactive/rng7.htm">here.</a> The
     *       Poisson process (and hence value returned) is bounded by 1000 * mean.
     *   <li>For large means, uses the rejection algorithm described in <br>
     *       Devroye, Luc. (1981).<i>The Computer Generation of Poisson Random Variables</i>
     *       <strong>Computing</strong> vol. 26 pp. 197-207.
     * </ul>
     *
     * @throws NotStrictlyPositiveException if {@code len <= 0}
     */
    public long nextPoisson(double mean) throws NotStrictlyPositiveException {
        return new PoissonDistribution(
                        getRandomGenerator(),
                        mean,
                        PoissonDistribution.DEFAULT_EPSILON,
                        PoissonDistribution.DEFAULT_MAX_ITERATIONS)
                .sample();
    }

    /** {@inheritDoc} */
    public double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException {
        if (sigma <= 0) {
            throw new NotStrictlyPositiveException(LocalizedFormats.STANDARD_DEVIATION, sigma);
        }
        return sigma * getRandomGenerator().nextGaussian() + mu;
    }

    /**
     * {@inheritDoc}
     *
     * <p><strong>Algorithm Description</strong>: Uses the Algorithm SA (Ahrens) from p. 876 in:
     * [1]: Ahrens, J. H. and Dieter, U. (1972). Computer methods for sampling from the exponential
     * and normal distributions. Communications of the ACM, 15, 873-882.
     */
    public double nextExponential(double mean) throws NotStrictlyPositiveException {
        return new ExponentialDistribution(
                        getRandomGenerator(),
                        mean,
                        ExponentialDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link
     * org.apache.commons.math3.distribution.GammaDistribution Gamma Distribution}.
     *
     * <p>This implementation uses the following algorithms:
     *
     * <p>For 0 < shape < 1: <br>
     * Ahrens, J. H. and Dieter, U., <i>Computer methods for sampling from gamma, beta, Poisson and
     * binomial distributions.</i> Computing, 12, 223-246, 1974.
     *
     * <p>For shape >= 1: <br>
     * Marsaglia and Tsang, <i>A Simple Method for Generating Gamma Variables.</i> ACM Transactions
     * on Mathematical Software, Volume 26 Issue 3, September, 2000.
     *
     * @param shape the median of the Gamma distribution
     * @param scale the scale parameter of the Gamma distribution
     * @return random value sampled from the Gamma(shape, scale) distribution
     * @throws NotStrictlyPositiveException if {@code shape <= 0} or {@code scale <= 0}.
     */
    public double nextGamma(double shape, double scale) throws NotStrictlyPositiveException {
        return new GammaDistribution(
                        getRandomGenerator(),
                        shape,
                        scale,
                        GammaDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link HypergeometricDistribution Hypergeometric
     * Distribution}.
     *
     * @param populationSize the population size of the Hypergeometric distribution
     * @param numberOfSuccesses number of successes in the population of the Hypergeometric
     *     distribution
     * @param sampleSize the sample size of the Hypergeometric distribution
     * @return random value sampled from the Hypergeometric(numberOfSuccesses, sampleSize)
     *     distribution
     * @throws NumberIsTooLargeException if {@code numberOfSuccesses > populationSize}, or {@code
     *     sampleSize > populationSize}.
     * @throws NotStrictlyPositiveException if {@code populationSize <= 0}.
     * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
     */
    public int nextHypergeometric(int populationSize, int numberOfSuccesses, int sampleSize)
            throws NotPositiveException, NotStrictlyPositiveException, NumberIsTooLargeException {
        return new HypergeometricDistribution(
                        getRandomGenerator(), populationSize, numberOfSuccesses, sampleSize)
                .sample();
    }

    /**
     * Generates a random value from the {@link PascalDistribution Pascal Distribution}.
     *
     * @param r the number of successes of the Pascal distribution
     * @param p the probability of success of the Pascal distribution
     * @return random value sampled from the Pascal(r, p) distribution
     * @throws NotStrictlyPositiveException if the number of successes is not positive
     * @throws OutOfRangeException if the probability of success is not in the range {@code [0, 1]}.
     */
    public int nextPascal(int r, double p)
            throws NotStrictlyPositiveException, OutOfRangeException {
        return new PascalDistribution(getRandomGenerator(), r, p).sample();
    }

    /**
     * Generates a random value from the {@link TDistribution T Distribution}.
     *
     * @param df the degrees of freedom of the T distribution
     * @return random value from the T(df) distribution
     * @throws NotStrictlyPositiveException if {@code df <= 0}
     */
    public double nextT(double df) throws NotStrictlyPositiveException {
        return new TDistribution(
                        getRandomGenerator(), df, TDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link WeibullDistribution Weibull Distribution}.
     *
     * @param shape the shape parameter of the Weibull distribution
     * @param scale the scale parameter of the Weibull distribution
     * @return random value sampled from the Weibull(shape, size) distribution
     * @throws NotStrictlyPositiveException if {@code shape <= 0} or {@code scale <= 0}.
     */
    public double nextWeibull(double shape, double scale) throws NotStrictlyPositiveException {
        return new WeibullDistribution(
                        getRandomGenerator(),
                        shape,
                        scale,
                        WeibullDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link ZipfDistribution Zipf Distribution}.
     *
     * @param numberOfElements the number of elements of the ZipfDistribution
     * @param exponent the exponent of the ZipfDistribution
     * @return random value sampled from the Zipf(numberOfElements, exponent) distribution
     * @exception NotStrictlyPositiveException if {@code numberOfElements <= 0} or {@code exponent
     *     <= 0}.
     */
    public int nextZipf(int numberOfElements, double exponent) throws NotStrictlyPositiveException {
        return new ZipfDistribution(getRandomGenerator(), numberOfElements, exponent).sample();
    }

    /**
     * Generates a random value from the {@link BetaDistribution Beta Distribution}.
     *
     * @param alpha first distribution shape parameter
     * @param beta second distribution shape parameter
     * @return random value sampled from the beta(alpha, beta) distribution
     */
    public double nextBeta(double alpha, double beta) {
        return new BetaDistribution(
                        getRandomGenerator(),
                        alpha,
                        beta,
                        BetaDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link BinomialDistribution Binomial Distribution}.
     *
     * @param numberOfTrials number of trials of the Binomial distribution
     * @param probabilityOfSuccess probability of success of the Binomial distribution
     * @return random value sampled from the Binomial(numberOfTrials, probabilityOfSuccess)
     *     distribution
     */
    public int nextBinomial(int numberOfTrials, double probabilityOfSuccess) {
        return new BinomialDistribution(getRandomGenerator(), numberOfTrials, probabilityOfSuccess)
                .sample();
    }

    /**
     * Generates a random value from the {@link CauchyDistribution Cauchy Distribution}.
     *
     * @param median the median of the Cauchy distribution
     * @param scale the scale parameter of the Cauchy distribution
     * @return random value sampled from the Cauchy(median, scale) distribution
     */
    public double nextCauchy(double median, double scale) {
        return new CauchyDistribution(
                        getRandomGenerator(),
                        median,
                        scale,
                        CauchyDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link ChiSquaredDistribution ChiSquare Distribution}.
     *
     * @param df the degrees of freedom of the ChiSquare distribution
     * @return random value sampled from the ChiSquare(df) distribution
     */
    public double nextChiSquare(double df) {
        return new ChiSquaredDistribution(
                        getRandomGenerator(),
                        df,
                        ChiSquaredDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * Generates a random value from the {@link FDistribution F Distribution}.
     *
     * @param numeratorDf the numerator degrees of freedom of the F distribution
     * @param denominatorDf the denominator degrees of freedom of the F distribution
     * @return random value sampled from the F(numeratorDf, denominatorDf) distribution
     * @throws NotStrictlyPositiveException if {@code numeratorDf <= 0} or {@code denominatorDf <=
     *     0}.
     */
    public double nextF(double numeratorDf, double denominatorDf)
            throws NotStrictlyPositiveException {
        return new FDistribution(
                        getRandomGenerator(),
                        numeratorDf,
                        denominatorDf,
                        FDistribution.DEFAULT_INVERSE_ABSOLUTE_ACCURACY)
                .sample();
    }

    /**
     * {@inheritDoc}
     *
     * <p><strong>Algorithm Description</strong>: scales the output of Random.nextDouble(), but
     * rejects 0 values (i.e., will generate another random double if Random.nextDouble() returns
     * 0). This is necessary to provide a symmetric output interval (both endpoints excluded).
     *
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     * @throws NotFiniteNumberException if one of the bounds is infinite
     * @throws NotANumberException if one of the bounds is NaN
     */
    public double nextUniform(double lower, double upper)
            throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException {
        return nextUniform(lower, upper, false);
    }

    /**
     * {@inheritDoc}
     *
     * <p><strong>Algorithm Description</strong>: if the lower bound is excluded, scales the output
     * of Random.nextDouble(), but rejects 0 values (i.e., will generate another random double if
     * Random.nextDouble() returns 0). This is necessary to provide a symmetric output interval
     * (both endpoints excluded).
     *
     * @throws NumberIsTooLargeException if {@code lower >= upper}
     * @throws NotFiniteNumberException if one of the bounds is infinite
     * @throws NotANumberException if one of the bounds is NaN
     */
    public double nextUniform(double lower, double upper, boolean lowerInclusive)
            throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException {

        if (lower >= upper) {
            throw new NumberIsTooLargeException(
                    LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper, false);
        }

        if (Double.isInfinite(lower)) {
            throw new NotFiniteNumberException(LocalizedFormats.INFINITE_BOUND, lower);
        }
        if (Double.isInfinite(upper)) {
            throw new NotFiniteNumberException(LocalizedFormats.INFINITE_BOUND, upper);
        }

        if (Double.isNaN(lower) || Double.isNaN(upper)) {
            throw new NotANumberException();
        }

        final RandomGenerator generator = getRandomGenerator();

        // ensure nextDouble() isn't 0.0
        double u = generator.nextDouble();
        while (!lowerInclusive && u <= 0.0) {
            u = generator.nextDouble();
        }

        return u * upper + (1.0 - u) * lower;
    }

    /**
     * {@inheritDoc}
     *
     * <p>This method calls {@link MathArrays#shuffle(int[],RandomGenerator) MathArrays.shuffle} in
     * order to create a random shuffle of the set of natural numbers {@code { 0, 1, ..., n - 1 }}.
     *
     * @throws NumberIsTooLargeException if {@code k > n}.
     * @throws NotStrictlyPositiveException if {@code k <= 0}.
     */
    public int[] nextPermutation(int n, int k)
            throws NumberIsTooLargeException, NotStrictlyPositiveException {
        if (k > n) {
            throw new NumberIsTooLargeException(LocalizedFormats.PERMUTATION_EXCEEDS_N, k, n, true);
        }
        if (k <= 0) {
            throw new NotStrictlyPositiveException(LocalizedFormats.PERMUTATION_SIZE, k);
        }

        int[] index = MathArrays.natural(n);
        MathArrays.shuffle(index, getRandomGenerator());

        // Return a new array containing the first "k" entries of "index".
        return MathArrays.copyOf(index, k);
    }

    /**
     * {@inheritDoc}
     *
     * <p>This method calls {@link #nextPermutation(int,int) nextPermutation(c.size(), k)} in order
     * to sample the collection.
     */
    public Object[] nextSample(Collection<?> c, int k)
            throws NumberIsTooLargeException, NotStrictlyPositiveException {

        int len = c.size();
        if (k > len) {
            throw new NumberIsTooLargeException(
                    LocalizedFormats.SAMPLE_SIZE_EXCEEDS_COLLECTION_SIZE, k, len, true);
        }
        if (k <= 0) {
            throw new NotStrictlyPositiveException(LocalizedFormats.NUMBER_OF_SAMPLES, k);
        }

        Object[] objects = c.toArray();
        int[] index = nextPermutation(len, k);
        Object[] result = new Object[k];
        for (int i = 0; i < k; i++) {
            result[i] = objects[index[i]];
        }
        return result;
    }

    /**
     * Reseeds the random number generator with the supplied seed.
     *
     * <p>Will create and initialize if null.
     *
     * @param seed the seed value to use
     */
    public void reSeed(long seed) {
        getRandomGenerator().setSeed(seed);
    }

    /**
     * Reseeds the secure random number generator with the current time in milliseconds.
     *
     * <p>Will create and initialize if null.
     */
    public void reSeedSecure() {
        getSecRan().setSeed(System.currentTimeMillis());
    }

    /**
     * Reseeds the secure random number generator with the supplied seed.
     *
     * <p>Will create and initialize if null.
     *
     * @param seed the seed value to use
     */
    public void reSeedSecure(long seed) {
        getSecRan().setSeed(seed);
    }

    /**
     * Reseeds the random number generator with {@code System.currentTimeMillis() +
     * System.identityHashCode(this))}.
     */
    public void reSeed() {
        getRandomGenerator().setSeed(System.currentTimeMillis() + System.identityHashCode(this));
    }

    /**
     * Sets the PRNG algorithm for the underlying SecureRandom instance using the Security Provider
     * API. The Security Provider API is defined in <a href =
     * "http://java.sun.com/j2se/1.3/docs/guide/security/CryptoSpec.html#AppA"> Java Cryptography
     * Architecture API Specification & Reference.</a>
     *
     * <p><strong>USAGE NOTE:</strong> This method carries <i>significant</i> overhead and may take
     * several seconds to execute.
     *
     * @param algorithm the name of the PRNG algorithm
     * @param provider the name of the provider
     * @throws NoSuchAlgorithmException if the specified algorithm is not available
     * @throws NoSuchProviderException if the specified provider is not installed
     */
    public void setSecureAlgorithm(String algorithm, String provider)
            throws NoSuchAlgorithmException, NoSuchProviderException {
        secRand =
                RandomGeneratorFactory.createRandomGenerator(
                        SecureRandom.getInstance(algorithm, provider));
    }

    /**
     * Returns the RandomGenerator used to generate non-secure random data.
     *
     * <p>Creates and initializes a default generator if null. Uses a {@link Well19937c} generator
     * with {@code System.currentTimeMillis() + System.identityHashCode(this))} as the default seed.
     *
     * @return the Random used to generate random data
     * @since 3.2
     */
    public RandomGenerator getRandomGenerator() {
        if (rand == null) {
            initRan();
        }
        return rand;
    }

    /**
     * Sets the default generator to a {@link Well19937c} generator seeded with {@code
     * System.currentTimeMillis() + System.identityHashCode(this))}.
     */
    private void initRan() {
        rand = new Well19937c(System.currentTimeMillis() + System.identityHashCode(this));
    }

    /**
     * Returns the SecureRandom used to generate secure random data.
     *
     * <p>Creates and initializes if null. Uses {@code System.currentTimeMillis() +
     * System.identityHashCode(this)} as the default seed.
     *
     * @return the SecureRandom used to generate secure random data, wrapped in a {@link
     *     RandomGenerator}.
     */
    private RandomGenerator getSecRan() {
        if (secRand == null) {
            secRand = RandomGeneratorFactory.createRandomGenerator(new SecureRandom());
            secRand.setSeed(System.currentTimeMillis() + System.identityHashCode(this));
        }
        return secRand;
    }
}