| 1 |
// (C) Copyright John Maddock 2006. |
| 2 |
// (C) Copyright Matt Borland 2024. |
| 3 |
// Use, modification and distribution are subject to the |
| 4 |
// Boost Software License, Version 1.0. (See accompanying file |
| 5 |
// LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| 6 |
|
| 7 |
// |
| 8 |
// This is not a complete header file, it is included by gamma.hpp |
| 9 |
// after it has defined it's definitions. This inverts the incomplete |
| 10 |
// gamma functions P and Q on the first parameter "a" using a generic |
| 11 |
// root finding algorithm (TOMS Algorithm 748). |
| 12 |
// |
| 13 |
|
| 14 |
#ifndef BOOST_MATH_SP_DETAIL_GAMMA_INVA |
| 15 |
#define BOOST_MATH_SP_DETAIL_GAMMA_INVA |
| 16 |
|
| 17 |
#ifdef _MSC_VER |
| 18 |
#pragma once |
| 19 |
#endif |
| 20 |
|
| 21 |
#include <boost/math/tools/config.hpp> |
| 22 |
#include <boost/math/tools/toms748_solve.hpp> |
| 23 |
|
| 24 |
namespace boost{ namespace math{ |
| 25 |
|
| 26 |
#ifdef BOOST_MATH_HAS_NVRTC |
| 27 |
template <typename T, typename Policy> |
| 28 |
BOOST_MATH_GPU_ENABLED auto erfc_inv(T x, const Policy&); |
| 29 |
#endif |
| 30 |
|
| 31 |
namespace detail{ |
| 32 |
|
| 33 |
template <class T, class Policy> |
| 34 |
struct gamma_inva_t |
| 35 |
{ |
| 36 |
BOOST_MATH_GPU_ENABLED gamma_inva_t(T z_, T p_, bool invert_) : z(z_), p(p_), invert(invert_) {} |
| 37 |
BOOST_MATH_GPU_ENABLED T operator()(T a) |
| 38 |
{ |
| 39 |
return invert ? p - boost::math::gamma_q(a, z, Policy()) : boost::math::gamma_p(a, z, Policy()) - p; |
| 40 |
} |
| 41 |
private: |
| 42 |
T z, p; |
| 43 |
bool invert; |
| 44 |
}; |
| 45 |
|
| 46 |
template <class T, class Policy> |
| 47 |
BOOST_MATH_GPU_ENABLED T inverse_poisson_cornish_fisher(T lambda, T p, T q, const Policy& pol) |
| 48 |
{ |
| 49 |
BOOST_MATH_STD_USING |
| 50 |
// mean: |
| 51 |
T m = lambda; |
| 52 |
// standard deviation: |
| 53 |
T sigma = sqrt(lambda); |
| 54 |
// skewness |
| 55 |
T sk = 1 / sigma; |
| 56 |
// kurtosis: |
| 57 |
// T k = 1/lambda; |
| 58 |
// Get the inverse of a std normal distribution: |
| 59 |
T x = boost::math::erfc_inv(p > q ? 2 * q : 2 * p, pol) * constants::root_two<T>(); |
| 60 |
// Set the sign: |
| 61 |
if(p < 0.5) |
| 62 |
x = -x; |
| 63 |
T x2 = x * x; |
| 64 |
// w is correction term due to skewness |
| 65 |
T w = x + sk * (x2 - 1) / 6; |
| 66 |
/* |
| 67 |
// Add on correction due to kurtosis. |
| 68 |
// Disabled for now, seems to make things worse? |
| 69 |
// |
| 70 |
if(lambda >= 10) |
| 71 |
w += k * x * (x2 - 3) / 24 + sk * sk * x * (2 * x2 - 5) / -36; |
| 72 |
*/ |
| 73 |
w = m + sigma * w; |
| 74 |
return w > tools::min_value<T>() ? w : tools::min_value<T>(); |
| 75 |
} |
| 76 |
|
| 77 |
template <class T, class Policy> |
| 78 |
BOOST_MATH_GPU_ENABLED T gamma_inva_imp(const T& z, const T& p, const T& q, const Policy& pol) |
| 79 |
{ |
| 80 |
BOOST_MATH_STD_USING // for ADL of std lib math functions |
| 81 |
// |
| 82 |
// Special cases first: |
| 83 |
// |
| 84 |
if(p == 0) |
| 85 |
{ |
| 86 |
return policies::raise_overflow_error<T>("boost::math::gamma_p_inva<%1%>(%1%, %1%)", nullptr, Policy()); |
| 87 |
} |
| 88 |
if(q == 0) |
| 89 |
{ |
| 90 |
return tools::min_value<T>(); |
| 91 |
} |
| 92 |
// |
| 93 |
// Function object, this is the functor whose root |
| 94 |
// we have to solve: |
| 95 |
// |
| 96 |
gamma_inva_t<T, Policy> f(z, (p < q) ? p : q, (p < q) ? false : true); |
| 97 |
// |
| 98 |
// Tolerance: full precision. |
| 99 |
// |
| 100 |
tools::eps_tolerance<T> tol(policies::digits<T, Policy>()); |
| 101 |
// |
| 102 |
// Now figure out a starting guess for what a may be, |
| 103 |
// we'll start out with a value that'll put p or q |
| 104 |
// right bang in the middle of their range, the functions |
| 105 |
// are quite sensitive so we should need too many steps |
| 106 |
// to bracket the root from there: |
| 107 |
// |
| 108 |
T guess; |
| 109 |
T factor = 8; |
| 110 |
if(z >= 1) |
| 111 |
{ |
| 112 |
// |
| 113 |
// We can use the relationship between the incomplete |
| 114 |
// gamma function and the poisson distribution to |
| 115 |
// calculate an approximate inverse, for large z |
| 116 |
// this is actually pretty accurate, but it fails badly |
| 117 |
// when z is very small. Also set our step-factor according |
| 118 |
// to how accurate we think the result is likely to be: |
| 119 |
// |
| 120 |
guess = 1 + inverse_poisson_cornish_fisher(z, q, p, pol); |
| 121 |
if(z > 5) |
| 122 |
{ |
| 123 |
if(z > 1000) |
| 124 |
factor = 1.01f; |
| 125 |
else if(z > 50) |
| 126 |
factor = 1.1f; |
| 127 |
else if(guess > 10) |
| 128 |
factor = 1.25f; |
| 129 |
else |
| 130 |
factor = 2; |
| 131 |
if(guess < 1.1) |
| 132 |
factor = 8; |
| 133 |
} |
| 134 |
} |
| 135 |
else if(z > 0.5) |
| 136 |
{ |
| 137 |
guess = z * 1.2f; |
| 138 |
} |
| 139 |
else |
| 140 |
{ |
| 141 |
guess = -0.4f / log(z); |
| 142 |
} |
| 143 |
// |
| 144 |
// Max iterations permitted: |
| 145 |
// |
| 146 |
std::uintmax_t max_iter = policies::get_max_root_iterations<Policy>(); |
| 147 |
// |
| 148 |
// Use our generic derivative-free root finding procedure. |
| 149 |
// We could use Newton steps here, taking the PDF of the |
| 150 |
// Poisson distribution as our derivative, but that's |
| 151 |
// even worse performance-wise than the generic method :-( |
| 152 |
// |
| 153 |
std::pair<T, T> r = bracket_and_solve_root(f, guess, factor, false, tol, max_iter, pol); |
| 154 |
if(max_iter >= policies::get_max_root_iterations<Policy>()) |
| 155 |
return policies::raise_evaluation_error<T>("boost::math::gamma_p_inva<%1%>(%1%, %1%)", "Unable to locate the root within a reasonable number of iterations, closest approximation so far was %1%", r.first, pol); |
| 156 |
return (r.first + r.second) / 2; |
| 157 |
} |
| 158 |
|
| 159 |
} // namespace detail |
| 160 |
|
| 161 |
template <class T1, class T2, class Policy> |
| 162 |
BOOST_MATH_GPU_ENABLED inline typename tools::promote_args<T1, T2>::type |
| 163 |
gamma_p_inva(T1 x, T2 p, const Policy& pol) |
| 164 |
{ |
| 165 |
typedef typename tools::promote_args<T1, T2>::type result_type; |
| 166 |
typedef typename policies::evaluation<result_type, Policy>::type value_type; |
| 167 |
typedef typename policies::normalise< |
| 168 |
Policy, |
| 169 |
policies::promote_float<false>, |
| 170 |
policies::promote_double<false>, |
| 171 |
policies::discrete_quantile<>, |
| 172 |
policies::assert_undefined<> >::type forwarding_policy; |
| 173 |
|
| 174 |
if(p == 0) |
| 175 |
{ |
| 176 |
policies::raise_overflow_error<result_type>("boost::math::gamma_p_inva<%1%>(%1%, %1%)", nullptr, Policy()); |
| 177 |
} |
| 178 |
if(p == 1) |
| 179 |
{ |
| 180 |
return tools::min_value<result_type>(); |
| 181 |
} |
| 182 |
|
| 183 |
return policies::checked_narrowing_cast<result_type, forwarding_policy>( |
| 184 |
detail::gamma_inva_imp( |
| 185 |
static_cast<value_type>(x), |
| 186 |
static_cast<value_type>(p), |
| 187 |
static_cast<value_type>(1 - static_cast<value_type>(p)), |
| 188 |
pol), "boost::math::gamma_p_inva<%1%>(%1%, %1%)"); |
| 189 |
} |
| 190 |
|
| 191 |
template <class T1, class T2, class Policy> |
| 192 |
BOOST_MATH_GPU_ENABLED inline typename tools::promote_args<T1, T2>::type |
| 193 |
gamma_q_inva(T1 x, T2 q, const Policy& pol) |
| 194 |
{ |
| 195 |
typedef typename tools::promote_args<T1, T2>::type result_type; |
| 196 |
typedef typename policies::evaluation<result_type, Policy>::type value_type; |
| 197 |
typedef typename policies::normalise< |
| 198 |
Policy, |
| 199 |
policies::promote_float<false>, |
| 200 |
policies::promote_double<false>, |
| 201 |
policies::discrete_quantile<>, |
| 202 |
policies::assert_undefined<> >::type forwarding_policy; |
| 203 |
|
| 204 |
if(q == 1) |
| 205 |
{ |
| 206 |
policies::raise_overflow_error<result_type>("boost::math::gamma_q_inva<%1%>(%1%, %1%)", nullptr, Policy()); |
| 207 |
} |
| 208 |
if(q == 0) |
| 209 |
{ |
| 210 |
return tools::min_value<result_type>(); |
| 211 |
} |
| 212 |
|
| 213 |
return policies::checked_narrowing_cast<result_type, forwarding_policy>( |
| 214 |
detail::gamma_inva_imp( |
| 215 |
static_cast<value_type>(x), |
| 216 |
static_cast<value_type>(1 - static_cast<value_type>(q)), |
| 217 |
static_cast<value_type>(q), |
| 218 |
pol), "boost::math::gamma_q_inva<%1%>(%1%, %1%)"); |
| 219 |
} |
| 220 |
|
| 221 |
template <class T1, class T2> |
| 222 |
BOOST_MATH_GPU_ENABLED inline typename tools::promote_args<T1, T2>::type |
| 223 |
gamma_p_inva(T1 x, T2 p) |
| 224 |
{ |
| 225 |
return boost::math::gamma_p_inva(x, p, policies::policy<>()); |
| 226 |
} |
| 227 |
|
| 228 |
template <class T1, class T2> |
| 229 |
BOOST_MATH_GPU_ENABLED inline typename tools::promote_args<T1, T2>::type |
| 230 |
gamma_q_inva(T1 x, T2 q) |
| 231 |
{ |
| 232 |
return boost::math::gamma_q_inva(x, q, policies::policy<>()); |
| 233 |
} |
| 234 |
|
| 235 |
} // namespace math |
| 236 |
} // namespace boost |
| 237 |
|
| 238 |
#endif // BOOST_MATH_SP_DETAIL_GAMMA_INVA |
| 239 |
|
| 240 |
|
| 241 |
|