***************************************************** Incomplete Gamma and Generalized Exponential Integral ***************************************************** GNSTLIB implements normalized and non-normalized incomplete gamma functions and the generalized exponential integral for real parameters and argument. This set of functions is included in the main header file: .. code-block:: C++ #include ========================== Incomplete gamma functions ========================== The incomplete gamma functions are defined by .. math:: \gamma(a, x) = \int_0^x t^{a-1} e^{-t} \mathop{dt}, \quad \Gamma(a, x) = \int_x^{\infty} t^{a-1} e^{-t} \mathop{dt}. Let us define the normalized forms .. math:: P(a, x) = \frac{1}{\Gamma(a)} \gamma(a, x), \quad Q(a, x) = \frac{1}{\Gamma(a)} \Gamma(a, x), where we assume that :math:`a` and :math:`x` are real positive numbers. The functions :math:`P(a, x)` and :math:`Q(a, x)` are the central gamma distribution function and its complementary function, respectively. The central gamma distribution functions satisfy the complementary relation .. math:: P(a, x) + Q(a, x) = 1. These distribution functions which appear in many problems of applied probability include, as particular case, the standard chi-square probability functions :math:`P(\chi^2| \nu)` and :math:`Q(\chi^2| \nu)` with parameters :math:`a = \nu / 2` and :math:`x = \chi^2 / 2`. The implementation of the central gamma distribution functions or normalized incomplete gamma functions is described in [1] and is based on GammaCHI package, see http://www.sciencedirect.com/science/article/pii/S0010465515000107. GNSTLIB::gammainc_p ------------------- .. cpp:function:: double gammainc_p(const double a, const double x, int& err_id) Computes the normalized lower incomplete gamma function :math:`P(a, x)` for positive real parameter and argument. #. **Arguments:** * **a**: (double) - *argument*. *Constraint*: **a** :math:`> 0`. * **x**: (double) - *argument*. *Constraint*: **x** :math:`\ge 0`. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = 4: Parameter **a** :math:`\le` 0.0, NaN is returned. * ``err_id`` = 5: Argument **x** is negative, NaN is returned. * ``err_id`` = -1: Argument **v** and/or **x** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::gammainc_q ------------------- .. cpp:function:: double gammainc_q(const double a, const double x, int& err_id) Computes the normalized upper incomplete gamma function :math:`Q(a, x)` for positive real parameter and argument. #. **Arguments:** * **a**: (double) - *argument*. *Constraint*: **a** :math:`> 0`. * **x**: (double) - *argument*. *Constraint*: **x** :math:`\ge 0`. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = 4: Parameter **a** :math:`\le` 0.0, NaN is returned. * ``err_id`` = 5: Argument **x** is negative, NaN is returned. * ``err_id`` = -1: Argument **v** and/or **x** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::gammainc_lower ----------------------- .. cpp:function:: double gammainc_lower(const double a, const double x, int& err_id) GNSTLIB::gammainc_upper ----------------------- .. cpp:function:: double gammainc_upper(const double a, const double x, int& err_id) GNSTLIB::gammainc_tricomi ------------------------- .. cpp:function:: double gammainc_tricomi(const double a, const double x, int& err_id) ================================ Generalized exponential integral ================================ GNSTLIB::expint --------------- .. cpp:function:: double expint(const double v, const double x, int& err_id) Computes the generalized exponential integral :math:`E_{\nu}(x)` for :math:`v \ge 0` and :math:`x \ge 0`. The generalized exponential integral is defined by .. math:: E_{\nu}(x) = \int_1^{\infty} e^{-xt} t^{-\nu} \mathop{dt}, \quad \nu \in \mathbb{R},\, x > 0. The generalized exponential integral can also be expressed in terms of the lower and upper incomplete gamma functions :cpp:func:`gammainc_lower()` and :cpp:func:`gammainc_upper()`, respectively. The implemented algorithm is described in [2]. #. **Arguments:** * **v**: (double) - *argument*. *Constraint*: **v** :math:`\ge 0`. * **x**: (double) - *argument*. *Constraint*: **x** :math:`\ge 0`. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = 4: Parameter **v** is negative, NaN is returned. * ``err_id`` = 5: Argument **x** is negative, NaN is returned. * ``err_id`` = -1: Argument **v** and/or **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: double expint(const int n, const double e, const double x, int& err_id) Computes the generalized exponential integral with positive real parameter and argument. For improved precision for :math:`\nu \approx |\nu|` and small :math:`x`, this routine accepts :math:`\nu` split into an integral and a decimal fractional part. Specifically :math:`\nu = n + e`, where :math:`|e| \le 0.5`. #. **Arguments:** * **n**: (int) - *argument*. *Constraint*: **v** :math:`\ge 0`. * **e**: (double) - *argument*. *Constraint*: :math:`|` **e** :math:`|\le 0.5`. * **x**: (double) - *argument*. *Constraint*: **x** :math:`\ge 0`. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = 4: Parameter **n** + **e** is negative, NaN is returned. * ``err_id`` = 5: Argument **x** is negative, NaN is returned. * ``err_id`` = 6: Argument :math:`|` **e** :math:`| > 0.5`, NaN is returned. * ``err_id`` = -1: Argument **v** and/or **x** is NaN or an unexpected error occurred. Contact the authors. ========== References ========== .. [1] A. Gil, J. Segura, and N. M. Temme. *Efficient and accurate algorithm for the computation and inversion of the incomplete gamma function ratios*. SIAM J. Scientific Computing, 34(6), (2012). .. [2] G. Navas-Palencia. *Fast and accurate algorithm for the generalized exponential integral* :math:`E_{\nu}(x)` *for positive real order*. Numerical Algorithms, (2017).