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 * https://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
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.distribution;
23
24 import org.hipparchus.exception.MathIllegalArgumentException;
25
26 /**
27 * Base interface for continuous distributions.
28 */
29 public interface RealDistribution {
30
31 /**
32 * For a random variable {@code X} whose values are distributed according
33 * to this distribution, this method returns {@code P(x0 < X <= x1)}.
34 *
35 * @param x0 the exclusive lower bound
36 * @param x1 the inclusive upper bound
37 * @return the probability that a random variable with this distribution
38 * takes a value between {@code x0} and {@code x1},
39 * excluding the lower and including the upper endpoint
40 * @throws MathIllegalArgumentException if {@code x0 > x1}
41 */
42 double probability(double x0, double x1) throws MathIllegalArgumentException;
43
44 /**
45 * Returns the probability density function (PDF) of this distribution
46 * evaluated at the specified point {@code x}. In general, the PDF is
47 * the derivative of the {@link #cumulativeProbability(double) CDF}.
48 * If the derivative does not exist at {@code x}, then an appropriate
49 * replacement should be returned, e.g. {@code Double.POSITIVE_INFINITY},
50 * {@code Double.NaN}, or the limit inferior or limit superior of the
51 * difference quotient.
52 *
53 * @param x the point at which the PDF is evaluated
54 * @return the value of the probability density function at point {@code x}
55 */
56 double density(double x);
57
58 /**
59 * Returns the natural logarithm of the probability density function
60 * (PDF) of this distribution evaluated at the specified point {@code x}.
61 * In general, the PDF is the derivative of the {@link #cumulativeProbability(double) CDF}.
62 * If the derivative does not exist at {@code x}, then an appropriate replacement
63 * should be returned, e.g. {@code Double.POSITIVE_INFINITY}, {@code Double.NaN},
64 * or the limit inferior or limit superior of the difference quotient. Note that
65 * due to the floating point precision and under/overflow issues, this method will
66 * for some distributions be more precise and faster than computing the logarithm of
67 * {@link #density(double)}.
68 *
69 * @param x the point at which the PDF is evaluated
70 * @return the logarithm of the value of the probability density function at point {@code x}
71 */
72 double logDensity(double x);
73
74 /**
75 * For a random variable {@code X} whose values are distributed according
76 * to this distribution, this method returns {@code P(X <= x)}. In other
77 * words, this method represents the (cumulative) distribution function
78 * (CDF) for this distribution.
79 *
80 * @param x the point at which the CDF is evaluated
81 * @return the probability that a random variable with this
82 * distribution takes a value less than or equal to {@code x}
83 */
84 double cumulativeProbability(double x);
85
86 /**
87 * Computes the quantile function of this distribution. For a random
88 * variable {@code X} distributed according to this distribution, the
89 * returned value is
90 * <ul>
91 * <li><code>inf{x in R | P(X<=x) >= p}</code> for {@code 0 < p <= 1},</li>
92 * <li><code>inf{x in R | P(X<=x) > 0}</code> for {@code p = 0}.</li>
93 * </ul>
94 *
95 * @param p the cumulative probability
96 * @return the smallest {@code p}-quantile of this distribution
97 * (largest 0-quantile for {@code p = 0})
98 * @throws MathIllegalArgumentException if {@code p < 0} or {@code p > 1}
99 */
100 double inverseCumulativeProbability(double p) throws MathIllegalArgumentException;
101
102 /**
103 * Use this method to get the numerical value of the mean of this
104 * distribution.
105 *
106 * @return the mean or {@code Double.NaN} if it is not defined
107 */
108 double getNumericalMean();
109
110 /**
111 * Use this method to get the numerical value of the variance of this
112 * distribution.
113 *
114 * @return the variance (possibly {@code Double.POSITIVE_INFINITY} as
115 * for certain cases in {@link org.hipparchus.distribution.continuous.TDistribution})
116 * or {@code Double.NaN} if it is not defined
117 */
118 double getNumericalVariance();
119
120 /**
121 * Access the lower bound of the support. This method must return the same
122 * value as {@code inverseCumulativeProbability(0)}. In other words, this
123 * method must return
124 * <p><code>inf {x in R | P(X <= x) > 0}</code>.</p>
125 *
126 * @return lower bound of the support (might be
127 * {@code Double.NEGATIVE_INFINITY})
128 */
129 double getSupportLowerBound();
130
131 /**
132 * Access the upper bound of the support. This method must return the same
133 * value as {@code inverseCumulativeProbability(1)}. In other words, this
134 * method must return
135 * <p><code>inf {x in R | P(X <= x) = 1}</code>.</p>
136 *
137 * @return upper bound of the support (might be
138 * {@code Double.POSITIVE_INFINITY})
139 */
140 double getSupportUpperBound();
141
142 /**
143 * Use this method to get information about whether the support is connected,
144 * i.e. whether all values between the lower and upper bound of the support
145 * are included in the support.
146 *
147 * @return whether the support is connected or not
148 */
149 boolean isSupportConnected();
150
151 }