/*
 * 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.NotStrictlyPositiveException;
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;
import org.apache.commons.math3.util.FastMath;

Implementation of the Cauchy distribution.
See Also:
Cauchy distribution (Wikipedia)
Cauchy Distribution (MathWorld)
Since:
1.1 (changed to concrete class in 3.0)/**
 * Implementation of the Cauchy distribution.
 *
 * @see <a href="http://en.wikipedia.org/wiki/Cauchy_distribution">Cauchy distribution (Wikipedia)</a>
 * @see <a href="http://mathworld.wolfram.com/CauchyDistribution.html">Cauchy Distribution (MathWorld)</a>
 * @since 1.1 (changed to concrete class in 3.0)
 */
public class CauchyDistribution extends AbstractRealDistribution {
    
Default inverse cumulative probability accuracy.
Since:
2.1/**
     * Default inverse cumulative probability accuracy.
     * @since 2.1
     */
    public static final double DEFAULT_INVERSE_ABSOLUTE_ACCURACY = 1e-9;
    
Serializable version identifier /** Serializable version identifier */
    private static final long serialVersionUID = 8589540077390120676L;
    
The median of this distribution. /** The median of this distribution. */
    private final double median;
    
The scale of this distribution. /** The scale of this distribution. */
    private final double scale;
    
Inverse cumulative probability accuracy /** Inverse cumulative probability accuracy */
    private final double solverAbsoluteAccuracy;

    
Creates a Cauchy distribution with the median equal to zero and scale
equal to one.
/**
     * Creates a Cauchy distribution with the median equal to zero and scale
     * equal to one.
     */
    public CauchyDistribution() {
        this(0, 1);
    }

    
Creates a Cauchy distribution using the given median and scale.

Note: this constructor will implicitly create an instance of Well19937c as random generator to be used for sampling only (see AbstractRealDistribution.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:
median – Median for this distribution.
scale – Scale parameter for this distribution./**
     * Creates a Cauchy distribution using the given median and scale.
     * <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 median Median for this distribution.
     * @param scale Scale parameter for this distribution.
     */
    public CauchyDistribution(double median, double scale) {
        this(median, scale, DEFAULT_INVERSE_ABSOLUTE_ACCURACY);
    }

    
Creates a Cauchy distribution using the given median and scale.

Note: this constructor will implicitly create an instance of Well19937c as random generator to be used for sampling only (see AbstractRealDistribution.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:
median – Median for this distribution.
scale – Scale parameter for this distribution.
inverseCumAccuracy – Maximum absolute error in inverse cumulative probability estimates (defaults to DEFAULT_INVERSE_ABSOLUTE_ACCURACY).
Throws:
NotStrictlyPositiveException – if scale <= 0.
Since:
2.1/**
     * Creates a Cauchy distribution using the given median and scale.
     * <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 median Median for this distribution.
     * @param scale Scale parameter for this distribution.
     * @param inverseCumAccuracy Maximum absolute error in inverse
     * cumulative probability estimates
     * (defaults to {@link #DEFAULT_INVERSE_ABSOLUTE_ACCURACY}).
     * @throws NotStrictlyPositiveException if {@code scale <= 0}.
     * @since 2.1
     */
    public CauchyDistribution(double median, double scale,
                              double inverseCumAccuracy) {
        this(new Well19937c(), median, scale, inverseCumAccuracy);
    }

    
Creates a Cauchy distribution.
Params:
rng – Random number generator.
median – Median for this distribution.
scale – Scale parameter for this distribution.
Throws:
NotStrictlyPositiveException – if scale <= 0.
Since:
3.3/**
     * Creates a Cauchy distribution.
     *
     * @param rng Random number generator.
     * @param median Median for this distribution.
     * @param scale Scale parameter for this distribution.
     * @throws NotStrictlyPositiveException if {@code scale <= 0}.
     * @since 3.3
     */
    public CauchyDistribution(RandomGenerator rng, double median, double scale) {
        this(rng, median, scale, DEFAULT_INVERSE_ABSOLUTE_ACCURACY);
    }

    
Creates a Cauchy distribution.
Params:
rng – Random number generator.
median – Median for this distribution.
scale – Scale parameter for this distribution.
inverseCumAccuracy – Maximum absolute error in inverse cumulative probability estimates (defaults to DEFAULT_INVERSE_ABSOLUTE_ACCURACY).
Throws:
NotStrictlyPositiveException – if scale <= 0.
Since:
3.1/**
     * Creates a Cauchy distribution.
     *
     * @param rng Random number generator.
     * @param median Median for this distribution.
     * @param scale Scale parameter for this distribution.
     * @param inverseCumAccuracy Maximum absolute error in inverse
     * cumulative probability estimates
     * (defaults to {@link #DEFAULT_INVERSE_ABSOLUTE_ACCURACY}).
     * @throws NotStrictlyPositiveException if {@code scale <= 0}.
     * @since 3.1
     */
    public CauchyDistribution(RandomGenerator rng,
                              double median,
                              double scale,
                              double inverseCumAccuracy) {
        super(rng);
        if (scale <= 0) {
            throw new NotStrictlyPositiveException(LocalizedFormats.SCALE, scale);
        }
        this.scale = scale;
        this.median = median;
        solverAbsoluteAccuracy = inverseCumAccuracy;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    public double cumulativeProbability(double x) {
        return 0.5 + (FastMath.atan((x - median) / scale) / FastMath.PI);
    }

    
Access the median.
Returns:
the median for this distribution./**
     * Access the median.
     *
     * @return the median for this distribution.
     */
    public double getMedian() {
        return median;
    }

    
Access the scale parameter.
Returns:
the scale parameter for this distribution./**
     * Access the scale parameter.
     *
     * @return the scale parameter for this distribution.
     */
    public double getScale() {
        return scale;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    public double density(double x) {
        final double dev = x - median;
        return (1 / FastMath.PI) * (scale / (dev * dev + scale * scale));
    }

    
{@inheritDoc} Returns Double.NEGATIVE_INFINITY when p == 0 and Double.POSITIVE_INFINITY when p == 1. /**
     * {@inheritDoc}
     *
     * Returns {@code Double.NEGATIVE_INFINITY} when {@code p == 0}
     * and {@code Double.POSITIVE_INFINITY} when {@code p == 1}.
     */
    @Override
    public double inverseCumulativeProbability(double p) throws OutOfRangeException {
        double ret;
        if (p < 0 || p > 1) {
            throw new OutOfRangeException(p, 0, 1);
        } else if (p == 0) {
            ret = Double.NEGATIVE_INFINITY;
        } else  if (p == 1) {
            ret = Double.POSITIVE_INFINITY;
        } else {
            ret = median + scale * FastMath.tan(FastMath.PI * (p - .5));
        }
        return ret;
    }

    
{@inheritDoc} /** {@inheritDoc} */
    @Override
    protected double getSolverAbsoluteAccuracy() {
        return solverAbsoluteAccuracy;
    }

    
{@inheritDoc}
The mean is always undefined no matter the parameters.
Returns:
mean (always Double.NaN)/**
     * {@inheritDoc}
     *
     * The mean is always undefined no matter the parameters.
     *
     * @return mean (always Double.NaN)
     */
    public double getNumericalMean() {
        return Double.NaN;
    }

    
{@inheritDoc}
The variance is always undefined no matter the parameters.
Returns:
variance (always Double.NaN)/**
     * {@inheritDoc}
     *
     * The variance is always undefined no matter the parameters.
     *
     * @return variance (always Double.NaN)
     */
    public double getNumericalVariance() {
        return Double.NaN;
    }

    
{@inheritDoc}
The lower bound of the support is always negative infinity no matter
the parameters.
Returns:
lower bound of the support (always Double.NEGATIVE_INFINITY)/**
     * {@inheritDoc}
     *
     * The lower bound of the support is always negative infinity no matter
     * the parameters.
     *
     * @return lower bound of the support (always Double.NEGATIVE_INFINITY)
     */
    public double getSupportLowerBound() {
        return Double.NEGATIVE_INFINITY;
    }

    
{@inheritDoc}
The upper bound of the support is always positive infinity no matter
the parameters.
Returns:
upper bound of the support (always Double.POSITIVE_INFINITY)/**
     * {@inheritDoc}
     *
     * The upper bound of the support is always positive infinity no matter
     * the parameters.
     *
     * @return upper bound of the support (always Double.POSITIVE_INFINITY)
     */
    public double getSupportUpperBound() {
        return Double.POSITIVE_INFINITY;
    }

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

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

    
{@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;
    }
}