xsf/xsf/gamma.rs
1use num_complex::Complex;
2
3use crate::utils::is_nonpos_int;
4use crate::xsf::c64::{C64, ViaC64};
5use crate::xsf::loggamma::cloggamma;
6
7pub trait GammaArg: crate::sealed::Sealed {
8 fn xsf_gamma(self) -> Self;
9}
10
11impl GammaArg for f64 {
12 #[inline]
13 fn xsf_gamma(self) -> Self {
14 crate::xsf::cephes::gamma(self)
15 }
16}
17
18impl GammaArg for Complex<f64> {
19 #[inline]
20 fn xsf_gamma(self) -> Self {
21 self.via(cgamma)
22 }
23}
24
25/// `xsf::gamma` for complex `z`, translated into pure Rust from `xsf/gamma.h` (scipy/xsf@56a9b96)
26pub(crate) fn cgamma(z: C64) -> C64 {
27 // Compute Gamma(z) using loggamma.
28 if z.is_real() && is_nonpos_int(z.re) {
29 // Poles
30 return C64::NAN;
31 }
32 cloggamma(z).exp()
33}
34
35/// Gamma function $\Gamma(z)$ for real or complex argument.
36///
37/// It is defined as [^DLMF]:
38///
39/// $$
40/// \Gamma(z) = \int_0^\infty t^{z-1} e^{-t} \dd t ,
41/// $$
42///
43/// for $\Re(z) > 0$, and is extended to the complex plane by analytic continuation.
44///
45/// # Type Parameters
46/// - `T`: either [`f64`] or [`Complex<f64>`](num_complex::Complex)
47///
48/// # See also
49/// - [`gammainc`]: Regularized lower incomplete gamma function, $P(a,x)$
50/// - [`gammaincc`]: Regularized upper incomplete gamma function, $Q(a,x)$
51/// - [`gammaln`]: Natural logarithm of the absolute value of the gamma function
52/// - [`rgamma`](crate::rgamma): Reciprocal of the gamma function, $1 \over \Gamma(z)$
53/// - [`scipy.special.gamma`][scipy]: Corresponding function in SciPy
54///
55/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gamma.html
56///
57/// [^DLMF]: NIST Digital Library of Mathematical Functions, <https://dlmf.nist.gov/5.2.E1>.
58#[must_use]
59#[inline]
60pub fn gamma<T: GammaArg>(z: T) -> T {
61 z.xsf_gamma()
62}
63
64/// Regularized lower incomplete gamma function $P(a,x)$
65///
66/// It is defined as [^DLMF]:
67///
68/// $$
69/// P(a,x)
70/// = {1 \over \Gamma(a)} \int_0^x t^{a-1} e^{-t} \dd t
71/// = 1 - Q(a,x) ,
72/// $$
73///
74/// for $a > 0$ and $x \ge 0$, with $Q(a,x)$ the regularized upper incomplete gamma function.
75///
76/// # Notes
77/// Unlike [`scipy.special.gammainc`][scipy], this wraps the `gammainc` Cephes routine [^CEPHES]
78/// rather than the Boost `gamma_p` routine [^BOOST].
79///
80/// # See also
81/// - [`gammaincc`]: Regularized upper incomplete gamma function, $Q(a,x)$
82/// - [`gammaincinv`]: Inverse of the regularized lower incomplete gamma function
83/// - [`gammainccinv`]: Inverse of the regularized upper incomplete gamma function
84/// - [`gamma`]: Gamma function $\Gamma(z)$
85/// - [`scipy.special.gammainc`][scipy]: Corresponding function in SciPy
86///
87/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammainc.html
88///
89/// [^DLMF]: NIST Digital Library of Mathematical Functions, <https://dlmf.nist.gov/8.2.E4>.
90/// [^CEPHES]: Cephes Math Library Release 2.0.
91/// [^BOOST]: The Boost Developers. “Boost C++ Libraries”, <https://www.boost.org>.
92#[doc(alias = "gamma_lr", alias = "gamma_p")]
93#[must_use]
94#[inline]
95pub fn gammainc(a: f64, x: f64) -> f64 {
96 crate::xsf::cephes::igam(a, x)
97}
98
99/// Regularized upper incomplete gamma function $Q(a,x)$
100///
101/// It is defined as [^DLMF]:
102///
103/// $$
104/// Q(a,x)
105/// = {1 \over \Gamma(a)} \int_x^\infty t^{a-1} e^{-t} \dd t
106/// = 1 - P(a,x) ,
107/// $$
108///
109/// for $a > 0$ and $x \ge 0$, with $P(a,x)$ the regularized lower incomplete gamma function.
110///
111/// # Notes
112/// Unlike [`scipy.special.gammaincc`][scipy], this wraps the `gammaincc` Cephes routine [^CEPHES]
113/// rather than the Boost `gamma_q` routine [^BOOST].
114///
115/// # See also
116/// - [`gammainc`]: Regularized lower incomplete gamma function, $P(a,x)$
117/// - [`gammaincinv`]: Inverse of the regularized lower incomplete gamma function
118/// - [`gammainccinv`]: Inverse of the regularized upper incomplete gamma function
119/// - [`gamma`]: Gamma function $\Gamma(z)$
120/// - [`scipy.special.gammaincc`][scipy]: Corresponding function in SciPy
121///
122/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammaincc.html
123///
124/// [^DLMF]: NIST Digital Library of Mathematical Functions, <https://dlmf.nist.gov/8.2.E4>.
125/// [^CEPHES]: Cephes Math Library Release 2.0.
126/// [^BOOST]: The Boost Developers. “Boost C++ Libraries”, <https://www.boost.org>.
127#[doc(alias = "gamma_ur", alias = "gamma_q")]
128#[must_use]
129#[inline]
130pub fn gammaincc(a: f64, x: f64) -> f64 {
131 crate::xsf::cephes::igamc(a, x)
132}
133
134/// Inverse of [`gammainc`]
135///
136/// Given an input $p \in \[0, 1\]$, returns $x$ such that $p = P(a,x)$.
137/// Here, $P$ is the regularized lower incomplete gamma function; see [`gammainc`].
138/// This is well-defined because the lower incomplete gamma function is monotonic [^DLMF].
139///
140/// # See also
141/// - [`gammainc`]: Regularized lower incomplete gamma function, $P(a,x)$
142/// - [`gammaincc`]: Regularized upper incomplete gamma function, $Q(a,x)$
143/// - [`gammainccinv`]: Inverse of the regularized upper incomplete gamma function
144/// - [`gamma`]: Gamma function $\Gamma(z)$
145/// - [`scipy.special.gammaincinv`][scipy]: Corresponding function in SciPy
146///
147/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammaincinv.html
148///
149/// [^DLMF]: NIST Digital Library of Mathematical Functions, <https://dlmf.nist.gov/8.2.E4>.
150#[must_use]
151#[inline]
152pub fn gammaincinv(a: f64, p: f64) -> f64 {
153 crate::xsf::cephes::igami(a, p)
154}
155
156/// Inverse of [`gammaincc`]
157///
158/// Given an input $p \in \[0, 1\]$, returns $x$ such that $p = Q(a,x)$.
159/// Here, $Q$ is the regularized upper incomplete gamma function; see [`gammaincc`].
160/// This is well-defined because the upper incomplete gamma function is monotonic [^DLMF].
161///
162/// # See also
163/// - [`gammainc`]: Regularized lower incomplete gamma function, $P(a,x)$
164/// - [`gammaincc`]: Regularized upper incomplete gamma function, $Q(a,x)$
165/// - [`gammaincinv`]: Inverse of the regularized lower incomplete gamma function
166/// - [`gamma`]: Gamma function $\Gamma(z)$
167/// - [`scipy.special.gammainccinv`][scipy]: Corresponding function in SciPy
168///
169/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammainccinv.html
170///
171/// [^DLMF]: NIST Digital Library of Mathematical Functions, <https://dlmf.nist.gov/8.2.E4>.
172#[must_use]
173#[inline]
174pub fn gammainccinv(a: f64, p: f64) -> f64 {
175 crate::xsf::cephes::igamci(a, p)
176}
177
178/// Logarithm of the absolute value of [`gamma`], $\ln{\abs{\Gamma(x)}}$
179///
180/// # See also
181/// - [`gamma`]: Gamma function $\Gamma(z)$
182/// - [`gammasgn`]: $\sgn \Gamma(x)$
183/// - [`scipy.special.gammaln`][scipy]: Corresponding function in SciPy
184///
185/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammaln.html
186#[doc(alias = "lgamma")]
187#[must_use]
188#[inline]
189pub fn gammaln(x: f64) -> f64 {
190 crate::xsf::cephes::lgam(x)
191}
192
193/// Sign of the Gamma function, $\sgn \Gamma(x)$
194///
195/// Since the Gamma function is never zero, this is always either `1.0` or `-1.0` (or [`f64::NAN`]).
196///
197/// # See also
198/// - [`gamma`]: Gamma function $\Gamma(z)$
199/// - [`gammaln`]: Natural logarithm of the absolute value of the gamma function
200/// - [`scipy.special.gammasgn`][scipy]: Corresponding function in SciPy
201///
202/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammasgn.html
203#[must_use]
204#[inline]
205pub fn gammasgn(x: f64) -> f64 {
206 crate::xsf::cephes::gammasgn(x)
207}