/*
 * 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.distribution;

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.random.RandomGenerator;
import org.apache.commons.math3.random.Well19937c;

Implementation of the uniform real distribution.
See Also:
Uniform distribution (continuous), at Wikipedia
Since:
3.0/**
 * Implementation of the uniform real distribution.
 *
 * @see <a href="http://en.wikipedia.org/wiki/Uniform_distribution_(continuous)"
 * >Uniform distribution (continuous), at Wikipedia</a>
 *
 * @since 3.0
 */
public class UniformRealDistribution extends AbstractRealDistribution {
    
Default inverse cumulative probability accuracy.
Deprecated:
as of 3.2 not used anymore, will be removed in 4.0/** Default inverse cumulative probability accuracy.
     * @deprecated as of 3.2 not used anymore, will be removed in 4.0
     */
    @Deprecated
    public static final double DEFAULT_INVERSE_ABSOLUTE_ACCURACY = 1e-9;
    
Serializable version identifier. /** Serializable version identifier. */
    private static final long serialVersionUID = 20120109L;
    
Lower bound of this distribution (inclusive). /** Lower bound of this distribution (inclusive). */
    private final double lower;
    
Upper bound of this distribution (exclusive). /** Upper bound of this distribution (exclusive). */
    private final double upper;

    
Create a standard uniform real distribution with lower bound (inclusive)
equal to zero and upper bound (exclusive) equal to one.

Note: this constructor will implicitly create an instance of Well19937c as random generator to be used for sampling only (see sample() and AbstractRealDistribution.sample(int)). In case no sampling is needed for the created distribution, it is advised to pass null as random generator via the appropriate constructors to avoid the additional initialisation overhead. /**
     * Create a standard uniform real distribution with lower bound (inclusive)
     * equal to zero and upper bound (exclusive) equal to one.
     * <p>
     * <b>Note:</b> this constructor will implicitly create an instance of
     * {@link Well19937c} as random generator to be used for sampling only (see
     * {@link #sample()} and {@link #sample(int)}). In case no sampling is
     * needed for the created distribution, it is advised to pass {@code null}
     * as random generator via the appropriate constructors to avoid the
     * additional initialisation overhead.
     */
    public UniformRealDistribution() {
        this(0, 1);
    }

    
Create a uniform real distribution using the given lower and upper
bounds.

Note: this constructor will implicitly create an instance of Well19937c as random generator to be used for sampling only (see sample() and AbstractRealDistribution.sample(int)). In case no sampling is needed for the created distribution, it is advised to pass null as random generator via the appropriate constructors to avoid the additional initialisation overhead. 
Params:
lower – Lower bound of this distribution (inclusive).
upper – Upper bound of this distribution (exclusive).
Throws:
NumberIsTooLargeException – if lower >= upper./**
     * Create a uniform real distribution using the given lower and upper
     * bounds.
     * <p>
     * <b>Note:</b> this constructor will implicitly create an instance of
     * {@link Well19937c} as random generator to be used for sampling only (see
     * {@link #sample()} and {@link #sample(int)}). In case no sampling is
     * needed for the created distribution, it is advised to pass {@code null}
     * as random generator via the appropriate constructors to avoid the
     * additional initialisation overhead.
     *
     * @param lower Lower bound of this distribution (inclusive).
     * @param upper Upper bound of this distribution (exclusive).
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     */
    public UniformRealDistribution(double lower, double upper)
        throws NumberIsTooLargeException {
        this(new Well19937c(), lower, upper);
    }

    
Create a uniform distribution.
Params:
lower – Lower bound of this distribution (inclusive).
upper – Upper bound of this distribution (exclusive).
inverseCumAccuracy – Inverse cumulative probability accuracy.
Throws:
NumberIsTooLargeException – if lower >= upper.
Deprecated:
as of 3.2, inverse CDF is now calculated analytically, use UniformRealDistribution(double, double) instead./**
     * Create a uniform distribution.
     *
     * @param lower Lower bound of this distribution (inclusive).
     * @param upper Upper bound of this distribution (exclusive).
     * @param inverseCumAccuracy Inverse cumulative probability accuracy.
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     * @deprecated as of 3.2, inverse CDF is now calculated analytically, use
     *             {@link #UniformRealDistribution(double, double)} instead.
     */
    @Deprecated
    public UniformRealDistribution(double lower, double upper, double inverseCumAccuracy)
        throws NumberIsTooLargeException {
        this(new Well19937c(), lower, upper);
    }

    
Creates a uniform distribution.
Params:
rng – Random number generator.
lower – Lower bound of this distribution (inclusive).
upper – Upper bound of this distribution (exclusive).
inverseCumAccuracy – Inverse cumulative probability accuracy.
Throws:
NumberIsTooLargeException – if lower >= upper.
Since:
3.1
Deprecated:
as of 3.2, inverse CDF is now calculated analytically, use UniformRealDistribution(RandomGenerator, double, double) instead./**
     * Creates a uniform distribution.
     *
     * @param rng Random number generator.
     * @param lower Lower bound of this distribution (inclusive).
     * @param upper Upper bound of this distribution (exclusive).
     * @param inverseCumAccuracy Inverse cumulative probability accuracy.
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     * @since 3.1
     * @deprecated as of 3.2, inverse CDF is now calculated analytically, use
     *             {@link #UniformRealDistribution(RandomGenerator, double, double)}
     *             instead.
     */
    @Deprecated
    public UniformRealDistribution(RandomGenerator rng,
                                   double lower,
                                   double upper,
                                   double inverseCumAccuracy){
        this(rng, lower, upper);
    }

    
Creates a uniform distribution.
Params:
rng – Random number generator.
lower – Lower bound of this distribution (inclusive).
upper – Upper bound of this distribution (exclusive).
Throws:
NumberIsTooLargeException – if lower >= upper.
Since:
3.1/**
     * Creates a uniform distribution.
     *
     * @param rng Random number generator.
     * @param lower Lower bound of this distribution (inclusive).
     * @param upper Upper bound of this distribution (exclusive).
     * @throws NumberIsTooLargeException if {@code lower >= upper}.
     * @since 3.1
     */
    public UniformRealDistribution(RandomGenerator rng,
                                   double lower,
                                   double upper)
        throws NumberIsTooLargeException {
        super(rng);
        if (lower >= upper) {
            throw new NumberIsTooLargeException(
                            LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
                            lower, upper, false);
        }

        this.lower = lower;
        this.upper = upper;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    public double density(double x) {
        if (x < lower || x > upper) {
            return 0.0;
        }
        return 1 / (upper - lower);
    }

    
{@inheritDoc} /** {@inheritDoc} */
    public double cumulativeProbability(double x)  {
        if (x <= lower) {
            return 0;
        }
        if (x >= upper) {
            return 1;
        }
        return (x - lower) / (upper - lower);
    }

    
{@inheritDoc} /** {@inheritDoc} */
    @Override
    public double inverseCumulativeProbability(final double p)
            throws OutOfRangeException {
        if (p < 0.0 || p > 1.0) {
            throw new OutOfRangeException(p, 0, 1);
        }
        return p * (upper - lower) + lower;
    }

    
{@inheritDoc} For lower bound lower and upper bound upper, the mean is 0.5 * (lower + upper). /**
     * {@inheritDoc}
     *
     * For lower bound {@code lower} and upper bound {@code upper}, the mean is
     * {@code 0.5 * (lower + upper)}.
     */
    public double getNumericalMean() {
        return 0.5 * (lower + upper);
    }

    
{@inheritDoc} For lower bound lower and upper bound upper, the variance is (upper - lower)^2 / 12. /**
     * {@inheritDoc}
     *
     * For lower bound {@code lower} and upper bound {@code upper}, the
     * variance is {@code (upper - lower)^2 / 12}.
     */
    public double getNumericalVariance() {
        double ul = upper - lower;
        return ul * ul / 12;
    }

    
{@inheritDoc}
The lower bound of the support is equal to the lower bound parameter
of the distribution.
Returns:
lower bound of the support/**
     * {@inheritDoc}
     *
     * The lower bound of the support is equal to the lower bound parameter
     * of the distribution.
     *
     * @return lower bound of the support
     */
    public double getSupportLowerBound() {
        return lower;
    }

    
{@inheritDoc}
The upper bound of the support is equal to the upper bound parameter
of the distribution.
Returns:
upper bound of the support/**
     * {@inheritDoc}
     *
     * The upper bound of the support is equal to the upper bound parameter
     * of the distribution.
     *
     * @return upper bound of the support
     */
    public double getSupportUpperBound() {
        return upper;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    public boolean isSupportLowerBoundInclusive() {
        return true;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    public boolean isSupportUpperBoundInclusive() {
        return true;
    }

    
{@inheritDoc}
The support of this distribution is connected.
Returns:
true/**
     * {@inheritDoc}
     *
     * The support of this distribution is connected.
     *
     * @return {@code true}
     */
    public boolean isSupportConnected() {
        return true;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    @Override
    public double sample()  {
        final double u = random.nextDouble();
        return u * upper + (1 - u) * lower;
    }
}