GumbelDistribution.java

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

  18. import org.apache.commons.math3.exception.NotStrictlyPositiveException;
  19. import org.apache.commons.math3.exception.OutOfRangeException;
  20. import org.apache.commons.math3.exception.util.LocalizedFormats;
  21. import org.apache.commons.math3.random.RandomGenerator;
  22. import org.apache.commons.math3.random.Well19937c;
  23. import org.apache.commons.math3.util.FastMath;
  24. import org.apache.commons.math3.util.MathUtils;

  25. /**
  26.  * This class implements the Gumbel distribution.
  27.  *
  28.  * @see <a href="http://en.wikipedia.org/wiki/Gumbel_distribution">Gumbel Distribution (Wikipedia)</a>
  29.  * @see <a href="http://mathworld.wolfram.com/GumbelDistribution.html">Gumbel Distribution (Mathworld)</a>
  30.  *
  31.  * @since 3.4
  32.  */
  33. public class GumbelDistribution extends AbstractRealDistribution {

  34.     /** Serializable version identifier. */
  35.     private static final long serialVersionUID = 20141003;

  36.     /**
  37.      * Approximation of Euler's constant
  38.      * see http://mathworld.wolfram.com/Euler-MascheroniConstantApproximations.html
  39.      */
  40.     private static final double EULER = FastMath.PI / (2 * FastMath.E);

  41.     /** The location parameter. */
  42.     private final double mu;
  43.     /** The scale parameter. */
  44.     private final double beta;

  45.     /**
  46.      * Build a new instance.
  47.      * <p>
  48.      * <b>Note:</b> this constructor will implicitly create an instance of
  49.      * {@link Well19937c} as random generator to be used for sampling only (see
  50.      * {@link #sample()} and {@link #sample(int)}). In case no sampling is
  51.      * needed for the created distribution, it is advised to pass {@code null}
  52.      * as random generator via the appropriate constructors to avoid the
  53.      * additional initialisation overhead.
  54.      *
  55.      * @param mu location parameter
  56.      * @param beta scale parameter (must be positive)
  57.      * @throws NotStrictlyPositiveException if {@code beta <= 0}
  58.      */
  59.     public GumbelDistribution(double mu, double beta) {
  60.         this(new Well19937c(), mu, beta);
  61.     }

  62.     /**
  63.      * Build a new instance.
  64.      *
  65.      * @param rng Random number generator
  66.      * @param mu location parameter
  67.      * @param beta scale parameter (must be positive)
  68.      * @throws NotStrictlyPositiveException if {@code beta <= 0}
  69.      */
  70.     public GumbelDistribution(RandomGenerator rng, double mu, double beta) {
  71.         super(rng);

  72.         if (beta <= 0) {
  73.             throw new NotStrictlyPositiveException(LocalizedFormats.SCALE, beta);
  74.         }

  75.         this.beta = beta;
  76.         this.mu = mu;
  77.     }

  78.     /**
  79.      * Access the location parameter, {@code mu}.
  80.      *
  81.      * @return the location parameter.
  82.      */
  83.     public double getLocation() {
  84.         return mu;
  85.     }

  86.     /**
  87.      * Access the scale parameter, {@code beta}.
  88.      *
  89.      * @return the scale parameter.
  90.      */
  91.     public double getScale() {
  92.         return beta;
  93.     }

  94.     /** {@inheritDoc} */
  95.     public double density(double x) {
  96.         final double z = (x - mu) / beta;
  97.         final double t = FastMath.exp(-z);
  98.         return FastMath.exp(-z - t) / beta;
  99.     }

  100.     /** {@inheritDoc} */
  101.     public double cumulativeProbability(double x) {
  102.         final double z = (x - mu) / beta;
  103.         return FastMath.exp(-FastMath.exp(-z));
  104.     }

  105.     @Override
  106.     public double inverseCumulativeProbability(double p) throws OutOfRangeException {
  107.         if (p < 0.0 || p > 1.0) {
  108.             throw new OutOfRangeException(p, 0.0, 1.0);
  109.         } else if (p == 0) {
  110.             return Double.NEGATIVE_INFINITY;
  111.         } else if (p == 1) {
  112.             return Double.POSITIVE_INFINITY;
  113.         }
  114.         return mu - FastMath.log(-FastMath.log(p)) * beta;
  115.     }

  116.     /** {@inheritDoc} */
  117.     public double getNumericalMean() {
  118.         return mu + EULER * beta;
  119.     }

  120.     /** {@inheritDoc} */
  121.     public double getNumericalVariance() {
  122.         return (MathUtils.PI_SQUARED) / 6.0 * (beta * beta);
  123.     }

  124.     /** {@inheritDoc} */
  125.     public double getSupportLowerBound() {
  126.         return Double.NEGATIVE_INFINITY;
  127.     }

  128.     /** {@inheritDoc} */
  129.     public double getSupportUpperBound() {
  130.         return Double.POSITIVE_INFINITY;
  131.     }

  132.     /** {@inheritDoc} */
  133.     public boolean isSupportLowerBoundInclusive() {
  134.         return false;
  135.     }

  136.     /** {@inheritDoc} */
  137.     public boolean isSupportUpperBoundInclusive() {
  138.         return false;
  139.     }

  140.     /** {@inheritDoc} */
  141.     public boolean isSupportConnected() {
  142.         return true;
  143.     }

  144. }