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.math.special;
18
19 import java.io.Serializable;
20
21 import org.apache.commons.math.MathException;
22 import org.apache.commons.math.util.ContinuedFraction;
23
24 /**
25 * This is a utility class that provides computation methods related to the
26 * Beta family of functions.
27 *
28 * @version $Revision: 549278 $ $Date: 2007-06-20 15:24:04 -0700 (Wed, 20 Jun 2007) $
29 */
30 public class Beta implements Serializable {
31
32 /** Serializable version identifier */
33 private static final long serialVersionUID = -3833485397404128220L;
34
35 /** Maximum allowed numerical error. */
36 private static final double DEFAULT_EPSILON = 10e-15;
37
38 /**
39 * Default constructor. Prohibit instantiation.
40 */
41 private Beta() {
42 super();
43 }
44
45 /**
46 * Returns the
47 * <a href="http://mathworld.wolfram.com/RegularizedBetaFunction.html">
48 * regularized beta function</a> I(x, a, b).
49 *
50 * @param x the value.
51 * @param a the a parameter.
52 * @param b the b parameter.
53 * @return the regularized beta function I(x, a, b)
54 * @throws MathException if the algorithm fails to converge.
55 */
56 public static double regularizedBeta(double x, double a, double b)
57 throws MathException
58 {
59 return regularizedBeta(x, a, b, DEFAULT_EPSILON, Integer.MAX_VALUE);
60 }
61
62 /**
63 * Returns the
64 * <a href="http://mathworld.wolfram.com/RegularizedBetaFunction.html">
65 * regularized beta function</a> I(x, a, b).
66 *
67 * @param x the value.
68 * @param a the a parameter.
69 * @param b the b parameter.
70 * @param epsilon When the absolute value of the nth item in the
71 * series is less than epsilon the approximation ceases
72 * to calculate further elements in the series.
73 * @return the regularized beta function I(x, a, b)
74 * @throws MathException if the algorithm fails to converge.
75 */
76 public static double regularizedBeta(double x, double a, double b,
77 double epsilon) throws MathException
78 {
79 return regularizedBeta(x, a, b, epsilon, Integer.MAX_VALUE);
80 }
81
82 /**
83 * Returns the regularized beta function I(x, a, b).
84 *
85 * @param x the value.
86 * @param a the a parameter.
87 * @param b the b parameter.
88 * @param maxIterations Maximum number of "iterations" to complete.
89 * @return the regularized beta function I(x, a, b)
90 * @throws MathException if the algorithm fails to converge.
91 */
92 public static double regularizedBeta(double x, double a, double b,
93 int maxIterations) throws MathException
94 {
95 return regularizedBeta(x, a, b, DEFAULT_EPSILON, maxIterations);
96 }
97
98 /**
99 * Returns the regularized beta function I(x, a, b).
100 *
101 * The implementation of this method is based on:
102 * <ul>
103 * <li>
104 * <a href="http://mathworld.wolfram.com/RegularizedBetaFunction.html">
105 * Regularized Beta Function</a>.</li>
106 * <li>
107 * <a href="http://functions.wolfram.com/06.21.10.0001.01">
108 * Regularized Beta Function</a>.</li>
109 * </ul>
110 *
111 * @param x the value.
112 * @param a the a parameter.
113 * @param b the b parameter.
114 * @param epsilon When the absolute value of the nth item in the
115 * series is less than epsilon the approximation ceases
116 * to calculate further elements in the series.
117 * @param maxIterations Maximum number of "iterations" to complete.
118 * @return the regularized beta function I(x, a, b)
119 * @throws MathException if the algorithm fails to converge.
120 */
121 public static double regularizedBeta(double x, final double a,
122 final double b, double epsilon, int maxIterations) throws MathException
123 {
124 double ret;
125
126 if (Double.isNaN(x) || Double.isNaN(a) || Double.isNaN(b) || (x < 0) ||
127 (x > 1) || (a <= 0.0) || (b <= 0.0))
128 {
129 ret = Double.NaN;
130 } else if (x > (a + 1.0) / (a + b + 2.0)) {
131 ret = 1.0 - regularizedBeta(1.0 - x, b, a, epsilon, maxIterations);
132 } else {
133 ContinuedFraction fraction = new ContinuedFraction() {
134
135 private static final long serialVersionUID = -7658917278956100597L;
136
137 protected double getB(int n, double x) {
138 double ret;
139 double m;
140 if (n % 2 == 0) { // even
141 m = n / 2.0;
142 ret = (m * (b - m) * x) /
143 ((a + (2 * m) - 1) * (a + (2 * m)));
144 } else {
145 m = (n - 1.0) / 2.0;
146 ret = -((a + m) * (a + b + m) * x) /
147 ((a + (2 * m)) * (a + (2 * m) + 1.0));
148 }
149 return ret;
150 }
151
152 protected double getA(int n, double x) {
153 return 1.0;
154 }
155 };
156 ret = Math.exp((a * Math.log(x)) + (b * Math.log(1.0 - x)) -
157 Math.log(a) - logBeta(a, b, epsilon, maxIterations)) *
158 1.0 / fraction.evaluate(x, epsilon, maxIterations);
159 }
160
161 return ret;
162 }
163
164 /**
165 * Returns the natural logarithm of the beta function B(a, b).
166 *
167 * @param a the a parameter.
168 * @param b the b parameter.
169 * @return log(B(a, b))
170 */
171 public static double logBeta(double a, double b) {
172 return logBeta(a, b, DEFAULT_EPSILON, Integer.MAX_VALUE);
173 }
174
175 /**
176 * Returns the natural logarithm of the beta function B(a, b).
177 *
178 * The implementation of this method is based on:
179 * <ul>
180 * <li><a href="http://mathworld.wolfram.com/BetaFunction.html">
181 * Beta Function</a>, equation (1).</li>
182 * </ul>
183 *
184 * @param a the a parameter.
185 * @param b the b parameter.
186 * @param epsilon When the absolute value of the nth item in the
187 * series is less than epsilon the approximation ceases
188 * to calculate further elements in the series.
189 * @param maxIterations Maximum number of "iterations" to complete.
190 * @return log(B(a, b))
191 */
192 public static double logBeta(double a, double b, double epsilon,
193 int maxIterations) {
194
195 double ret;
196
197 if (Double.isNaN(a) || Double.isNaN(b) || (a <= 0.0) || (b <= 0.0)) {
198 ret = Double.NaN;
199 } else {
200 ret = Gamma.logGamma(a) + Gamma.logGamma(b) -
201 Gamma.logGamma(a + b);
202 }
203
204 return ret;
205 }
206 }