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.numbers.gamma;
18
19 /**
20 * <a href="https://mathworld.wolfram.com/IncompleteBetaFunction.html">
21 * Incomplete Beta function</a>.
22 *
23 * <p>\[ B_x(a,b) = \int_0^x t^{a-1}\,(1-t)^{b-1}\,dt \]
24 *
25 * <p>This code has been adapted from the <a href="https://www.boost.org/">Boost</a>
26 * {@code c++} implementation {@code <boost/math/special_functions/beta.hpp>}.
27 *
28 * @see
29 * <a href="https://www.boost.org/doc/libs/1_77_0/libs/math/doc/html/math_toolkit/sf_beta/ibeta_function.html">
30 * Boost C++ Incomplete Beta functions</a>
31 * @since 1.1
32 */
33 public final class IncompleteBeta {
34
35 /** Private constructor. */
36 private IncompleteBeta() {
37 // intentionally empty.
38 }
39
40 /**
41 * Computes the value of the
42 * <a href="https://mathworld.wolfram.com/IncompleteBetaFunction.html">
43 * incomplete beta function</a> B(x, a, b).
44 *
45 * <p>\[ B_x(a,b) = \int_0^x t^{a-1}\,(1-t)^{b-1}\,dt \]
46 *
47 * @param x Value.
48 * @param a Parameter {@code a}.
49 * @param b Parameter {@code b}.
50 * @return the incomplete beta function \( B_x(a, b) \).
51 * @throws ArithmeticException if the series evaluation fails to converge.
52 */
53 public static double value(double x,
54 double a,
55 double b) {
56 return BoostBeta.beta(a, b, x);
57 }
58
59 /**
60 * Computes the value of the
61 * <a href="https://mathworld.wolfram.com/IncompleteBetaFunction.html">
62 * incomplete beta function</a> B(x, a, b).
63 *
64 * <p>\[ B_x(a,b) = \int_0^x t^{a-1}\,(1-t)^{b-1}\,dt \]
65 *
66 * @param x the value.
67 * @param a Parameter {@code a}.
68 * @param b Parameter {@code b}.
69 * @param epsilon Tolerance in series evaluation.
70 * @param maxIterations Maximum number of iterations in series evaluation.
71 * @return the incomplete beta function \( B_x(a, b) \).
72 * @throws ArithmeticException if the series evaluation fails to converge.
73 */
74 public static double value(double x,
75 final double a,
76 final double b,
77 double epsilon,
78 int maxIterations) {
79 return BoostBeta.beta(a, b, x, new Policy(epsilon, maxIterations));
80 }
81
82 /**
83 * Computes the complement of the
84 * <a href="https://mathworld.wolfram.com/IncompleteBetaFunction.html">
85 * incomplete beta function</a> B(x, a, b).
86 *
87 * <p>\[ B(a, b) - B_x(a,b) = B_{1-x}(b, a) \]
88 *
89 * <p>where \( B(a, b) \) is the beta function.
90 *
91 * @param x Value.
92 * @param a Parameter {@code a}.
93 * @param b Parameter {@code b}.
94 * @return the complement of the incomplete beta function \( B(a, b) - B_x(a, b) \).
95 * @throws ArithmeticException if the series evaluation fails to converge.
96 */
97 public static double complement(double x,
98 double a,
99 double b) {
100 return BoostBeta.betac(a, b, x);
101 }
102
103 /**
104 * Computes the complement of the
105 * <a href="https://mathworld.wolfram.com/IncompleteBetaFunction.html">
106 * incomplete beta function</a> B(x, a, b).
107 *
108 * <p>\[ B(a, b) - B_x(a,b) = B_{1-x}(b, a) \]
109 *
110 * <p>where \( B(a, b) \) is the beta function.
111 *
112 * @param x the value.
113 * @param a Parameter {@code a}.
114 * @param b Parameter {@code b}.
115 * @param epsilon Tolerance in series evaluation.
116 * @param maxIterations Maximum number of iterations in series evaluation.
117 * @return the complement of the incomplete beta function \( B(a, b) - B_x(a, b) \).
118 * @throws ArithmeticException if the series evaluation fails to converge.
119 */
120 public static double complement(double x,
121 final double a,
122 final double b,
123 double epsilon,
124 int maxIterations) {
125 return BoostBeta.betac(a, b, x, new Policy(epsilon, maxIterations));
126 }
127 }