Skip to main content

xsf/
lib.rs

1//! This crate provides pure Rust implementations of `scipy.special` functions, translated from the
2//! [xsf](https://github.com/scipy/xsf/) C++ library that powers `scipy.special`.
3//!
4//! Most of the `scipy.special` functions are available. See the
5//! [`scipy.special` documentation](https://docs.scipy.org/doc/scipy/reference/special.html)
6//! for additional information.
7//!
8//! [`docs/accuracy.md`](https://github.com/jorenham/xsf-rust/blob/master/docs/accuracy.md)
9//! compares the accuracy of many of these functions with that of xsf and, where available, the Rust
10//! standard library.
11//!
12//! # Airy functions
13//!
14//! | Function           | Description                                                      |
15//! | ------------------ | ---------------------------------------------------------------- |
16//! | [`airy`]           | Airy functions and derivatives                                   |
17//! | [`airy_scaled`]    | Exponentially scaled Airy functions and derivatives              |
18//! | [`airy_ai_zeros`]  | Zeros and values of the Airy function Ai and its derivative      |
19//! | [`airy_bi_zeros`]  | Zeros and values of the Airy function Bi and its derivative      |
20//! | [`airy_integrals`] | Integrals of Airy functions                                      |
21//!
22//! # Elliptic functions and integrals
23//!
24//! | Function         | Description                                                 |
25//! | ---------------- | ----------------------------------------------------------- |
26//! | [`ellipj`]       | Jacobian elliptic functions                                 |
27//! | [`ellipk`]       | Complete elliptic integral of the first kind                |
28//! | [`ellipkm1`]     | Complete elliptic integral of the first kind around $m = 1$ |
29//! | [`ellipkinc`]    | Incomplete elliptic integral of the first kind              |
30//! | [`ellipe`]       | Complete elliptic integral of the second kind               |
31//! | [`ellipeinc`]    | Incomplete elliptic integral of the second kind             |
32//! | [`elliprc`]      | Degenerate symmetric elliptic integral                      |
33//! | [`elliprd`]      | Symmetric elliptic integral of the second kind              |
34//! | [`elliprf`]      | Completely-symmetric elliptic integral of the first kind    |
35//! | [`elliprg`]      | Completely-symmetric elliptic integral of the second kind   |
36//! | [`elliprj`]      | Symmetric elliptic integral of the third kind               |
37//!
38//! # Ellipsoidal harmonics
39//!
40//! | Function         | Description                                              |
41//! | ---------------- | -------------------------------------------------------- |
42//! | [`ellip_harm`]   | Ellipsoidal harmonic functions $E^p_n(s)$                |
43//! | [`ellip_harm_2`] | Ellipsoidal harmonic functions $F^p_n(s)$                |
44//! | [`ellip_normal`] | Ellipsoidal harmonic normalization constants $\gamma^p_n$ |
45//!
46//! # Bessel functions
47//!
48//! | Function                | Description                                                       |
49//! | ----------------------- | ----------------------------------------------------------------- |
50//! | [`bessel_j`]            | Bessel function of the first kind, $J_v(z)$                       |
51//! | [`bessel_je`]           | Exponentially scaled Bessel function of the first kind            |
52//! | [`bessel_y`]            | Bessel function of the second kind, $Y_v(z)$                      |
53//! | [`bessel_ye`]           | Exponentially scaled Bessel function of the second kind           |
54//! | [`bessel_i`]            | Modified Bessel function of the first kind, $I_v(z)$              |
55//! | [`bessel_ie`]           | Exponentially scaled modified Bessel function of the first kind   |
56//! | [`bessel_k`]            | Modified Bessel function of the second kind, $K_v(z)$             |
57//! | [`bessel_ke`]           | Exponentially scaled modified Bessel function of the second kind  |
58//! | [`hankel_1`]            | Hankel function of the first kind, $H_v^{(1)}(z)$                 |
59//! | [`hankel_1e`]           | Exponentially scaled Hankel function of the first kind            |
60//! | [`hankel_2`]            | Hankel function of the second kind, $H_v^{(2)}(z)$                |
61//! | [`hankel_2e`]           | Exponentially scaled Hankel function of the second kind           |
62//! | [`wright_bessel`]       | Wright's generalized Bessel function                              |
63//! | [`log_wright_bessel`]   | Natural logarithm of Wright's generalized Bessel function         |
64//! | [`jahnke_emden_lambda`] | Jahnke-Emden Lambda function $\Lambda_{\nu}(x)$ and derivatives   |
65//! | [`iv_ratio`]            | Ratio $I_v(x) / I_{v-1}(x)$ of modified Bessel functions          |
66//! | [`iv_ratio_c`]          | Complement of [`iv_ratio`], $1 - I_v(x) / I_{v-1}(x)$             |
67//! | [`iv_ratioinv`]         | Inverse of [`iv_ratio`] with respect to $x$                       |
68//!
69//! ## Zeros of Bessel functions
70//!
71//! | Function                  | Description                                                              |
72//! | ------------------------- | ------------------------------------------------------------------------ |
73//! | [`bessel_zeros`]          | Zeros of Bessel functions $J_v(x)$, $J_v\'(x)$, $Y_v(x)$, and $Y_v\'(x)$ |
74//! | [`bessel_j_jprime_zeros`] | Zeros of all $J_n(x)$ and $J_n\'(x)$, in ascending order                  |
75//! | [`bessel_y0_zeros`]       | Real or complex zeros of $Y_0(z)$                                        |
76//! | [`bessel_y1_zeros`]       | Real or complex zeros of $Y_1(z)$                                        |
77//! | [`bessel_y1_prime_zeros`] | Real or complex zeros of $Y_1\'(z)$                                      |
78//!
79//! ## Faster versions of common Bessel functions
80//!
81//! | Function       | Description                                                                 |
82//! | -------------- | --------------------------------------------------------------------------- |
83//! | [`bessel_j0`]  | Bessel function of the first kind of order 0, $J_0(x)$                      |
84//! | [`bessel_j1`]  | Bessel function of the first kind of order 1, $J_1(x)$                      |
85//! | [`bessel_y0`]  | Bessel function of the second kind of order 0, $Y_0(x)$                     |
86//! | [`bessel_y1`]  | Bessel function of the second kind of order 1, $Y_1(x)$                     |
87//! | [`bessel_i0`]  | Modified Bessel function of the first kind of order 0, $I_0(x)$             |
88//! | [`bessel_i0e`] | Exponentially scaled modified Bessel function of the first kind of order 0  |
89//! | [`bessel_i1`]  | Modified Bessel function of the first kind of order 1, $I_1(x)$             |
90//! | [`bessel_i1e`] | Exponentially scaled modified Bessel function of the first kind of order 1  |
91//! | [`bessel_k0`]  | Modified Bessel function of the second kind of order 0, $K_0(x)$            |
92//! | [`bessel_k0e`] | Exponentially scaled modified Bessel function of the second kind of order 0 |
93//! | [`bessel_k1`]  | Modified Bessel function of the second kind of order 1, $K_1(x)$            |
94//! | [`bessel_k1e`] | Exponentially scaled modified Bessel function of the second kind of order 1 |
95//!
96//! ## Integrals of Bessel functions
97//!
98//! | Function       | Description                                                                 |
99//! | -------------- | --------------------------------------------------------------------------- |
100//! | [`it1j0y0`]    | Integrals of Bessel functions of order 0                                    |
101//! | [`it2j0y0`]    | Integrals related to Bessel functions of order 0                            |
102//! | [`it1i0k0`]    | Integrals of modified Bessel functions of order 0                           |
103//! | [`it2i0k0`]    | Integrals related to modified Bessel functions of order 0                   |
104//! | [`besselpoly`] | Weighted integral of the Bessel function of the first kind                  |
105//!
106//! ## Derivatives of Bessel functions
107//!
108//! | Function           | Description                       |
109//! | ------------------ | --------------------------------- |
110//! | [`bessel_j_prime`] | $n$-th derivative of [`bessel_j`] |
111//! | [`bessel_y_prime`] | $n$-th derivative of [`bessel_y`] |
112//! | [`bessel_i_prime`] | $n$-th derivative of [`bessel_i`] |
113//! | [`bessel_k_prime`] | $n$-th derivative of [`bessel_k`] |
114//! | [`hankel_1_prime`] | $n$-th derivative of [`hankel_1`] |
115//! | [`hankel_2_prime`] | $n$-th derivative of [`hankel_2`] |
116//!
117//! ## Spherical Bessel functions
118//!
119//! | Function               | Description                                                     |
120//! | ---------------------- | --------------------------------------------------------------- |
121//! | [`sph_bessel_j`]       | Spherical Bessel function of the first kind, $j_n(z)$           |
122//! | [`sph_bessel_j_prime`] | Derivative of [`sph_bessel_j`], $j_n\'(z)$                      |
123//! | [`sph_bessel_y`]       | Spherical Bessel function of the second kind, $y_n(z)$          |
124//! | [`sph_bessel_y_prime`] | Derivative of [`sph_bessel_y`], $y_n\'(z)$                      |
125//! | [`sph_bessel_i`]       | Modified Spherical Bessel function of the first kind, $i_n(z)$  |
126//! | [`sph_bessel_i_prime`] | Derivative of [`sph_bessel_i`], $i_n\'(z)$                      |
127//! | [`sph_bessel_k`]       | Modified Spherical Bessel function of the second kind, $k_n(z)$ |
128//! | [`sph_bessel_k_prime`] | Derivative of [`sph_bessel_k`], $k_n\'(z)$                      |
129//!
130//! ## Riccati-Bessel functions
131//!
132//! | Function      | Description                                                   |
133//! | ------------- | ------------------------------------------------------------- |
134//! | [`riccati_j`] | Riccati-Bessel function of the first kind and its derivative  |
135//! | [`riccati_y`] | Riccati-Bessel function of the second kind and its derivative |
136//!
137//! # Struve functions
138//!
139//! | Function         | Description                                                   |
140//! | ---------------- | ------------------------------------------------------------- |
141//! | [`struve_h`]     | Struve function $H_{\nu}(x)$                                  |
142//! | [`struve_l`]     | Modified Struve function $L_{\nu}(x)$                         |
143//! | [`itstruve0`]    | Integral of the Struve function of order 0, $H_0(x)$          |
144//! | [`it2struve0`]   | Integral related to the Struve function of order 0            |
145//! | [`itmodstruve0`] | Integral of the modified Struve function of order 0, $L_0(x)$ |
146//!
147//! # Raw statistical functions
148//!
149//! ## Binomial distribution
150//!
151//! | Function   | Description                                            |
152//! | ---------- | ------------------------------------------------------ |
153//! | [`bdtr`]   | Cumulative distribution function                       |
154//! | [`bdtrc`]  | Complement of [`bdtr`]                                 |
155//! | [`bdtri`]  | Inverse of [`bdtr`]                                    |
156//! | [`bdtrik`] | Inverse of [`bdtr(k, n, p)`](bdtr) with respect to `k` |
157//! | [`bdtrin`] | Inverse of [`bdtr(k, n, p)`](bdtr) with respect to `n` |
158//!
159//! ## Beta distribution
160//!
161//! | Function    | Description                                                  |
162//! | ----------- | ------------------------------------------------------------ |
163//! | [`btdtria`] | Inverse of [`betainc(a, b, x)`](betainc) with respect to `a` |
164//! | [`btdtrib`] | Inverse of [`betainc(a, b, x)`](betainc) with respect to `b` |
165//!
166//! ## F distribution
167//!
168//! | Function     | Description                                            |
169//! | ------------ | ------------------------------------------------------ |
170//! | [`fdtr`]     | Cumulative distribution function                       |
171//! | [`fdtrc`]    | Complement of [`fdtr`]                                 |
172//! | [`fdtri`]    | Inverse of [`fdtr`]                                    |
173//! | [`fdtridfd`] | Inverse of [`fdtr(a, b, x)`](fdtr) with respect to `b` |
174//!
175//! ## Noncentral F distribution
176//!
177//! | Function       | Description                              |
178//! | -------------- | ---------------------------------------- |
179//! | [`ncfdtr`]     | Cumulative distribution function         |
180//! | [`ncfdtri`]    | Inverse of the CDF with respect to `f`   |
181//! | [`ncfdtridfd`] | Inverse of the CDF with respect to `dfd` |
182//! | [`ncfdtridfn`] | Inverse of the CDF with respect to `dfn` |
183//! | [`ncfdtrinc`]  | Inverse of the CDF with respect to `nc`  |
184//!
185//! ## Gamma distribution
186//!
187//! | Function   | Description                                            |
188//! | ---------- | ------------------------------------------------------ |
189//! | [`gdtr`]   | Cumulative distribution function                       |
190//! | [`gdtrc`]  | Complement of [`gdtr`]                                 |
191//! | [`gdtria`] | Inverse of [`gdtr(a, b, x)`](gdtr) with respect to `a` |
192//! | [`gdtrib`] | Inverse of [`gdtr(a, b, x)`](gdtr) with respect to `b` |
193//! | [`gdtrix`] | Inverse of [`gdtr(a, b, x)`](gdtr) with respect to `x` |
194//!
195//! ## Generalized hyperbolic distribution
196//!
197//! | Function                 | Description                        |
198//! | ------------------------ | ---------------------------------- |
199//! | [`genhyperbolic_pdf`]    | Probability density function       |
200//! | [`genhyperbolic_logpdf`] | Logarithm of [`genhyperbolic_pdf`] |
201//!
202//! ## Generalized inverse Gaussian distribution
203//!
204//! | Function               | Description                      |
205//! | ---------------------- | -------------------------------- |
206//! | [`geninvgauss_pdf`]    | Probability density function     |
207//! | [`geninvgauss_logpdf`] | Logarithm of [`geninvgauss_pdf`] |
208//!
209//! ## Negative binomial distribution
210//!
211//! | Function    | Description                                              |
212//! | ----------- | -------------------------------------------------------- |
213//! | [`nbdtr`]   | Cumulative distribution function                         |
214//! | [`nbdtrc`]  | Complement of [`nbdtr`]                                  |
215//! | [`nbdtri`]  | Inverse of [`nbdtr`]                                     |
216//! | [`nbdtrik`] | Inverse of [`nbdtr(k, n, p)`](nbdtr) with respect to `k` |
217//! | [`nbdtrin`] | Inverse of [`nbdtr(k, n, p)`](nbdtr) with respect to `n` |
218//!
219//! ## Noncentral t distribution
220//!
221//! | Function      | Description                             |
222//! | ------------- | --------------------------------------- |
223//! | [`nctdtr`]    | Cumulative distribution function        |
224//! | [`nctdtridf`] | Inverse of the CDF with respect to `df` |
225//! | [`nctdtrinc`] | Inverse of the CDF with respect to `nc` |
226//! | [`nctdtrit`]  | Inverse of the CDF with respect to `t`  |
227//!
228//! ## Normal distribution
229//!
230//! | Function      | Description                      |
231//! | ------------- | -------------------------------- |
232//! | [`ndtr`]      | Cumulative distribution function |
233//! | [`ndtri`]     | Inverse of [`ndtr`]              |
234//! | [`log_ndtr`]  | Logarithm of [`ndtr`]            |
235//! | [`ndtri_exp`] | Inverse of [`log_ndtr`]          |
236//! | [`nrdtrimn`]  | Mean, given `p`, `std`, and `x`  |
237//! | [`nrdtrisd`]  | Std, given `mean`, `p`, and `x`  |
238//!
239//! ## Poisson distribution
240//!
241//! | Function   | Description                                         |
242//! | ---------- | --------------------------------------------------- |
243//! | [`pdtr`]   | Cumulative distribution function                    |
244//! | [`pdtrc`]  | Complement of [`pdtr`]                              |
245//! | [`pdtri`]  | Inverse of [`pdtr`]                                 |
246//! | [`pdtrik`] | Inverse of [`pdtr(k, m)`](pdtr) with respect to `k` |
247//!
248//! ## Poisson binomial distribution
249//!
250//! | Function                  | Description                           |
251//! | ------------------------- | ------------------------------------- |
252//! | [`poisson_binom_cdf`]     | Cumulative distribution function      |
253//! | [`poisson_binom_pmf_all`] | Full probability mass function        |
254//! | [`poisson_binom_cdf_all`] | Full cumulative distribution function |
255//!
256//! ## Student's t distribution
257//!
258//! | Function     | Description                                             |
259//! | ------------ | ------------------------------------------------------- |
260//! | [`stdtr`]    | Cumulative distribution function                        |
261//! | [`stdtri`]   | Inverse of [`stdtr`]                                    |
262//! | [`stdtridf`] | Inverse of [`stdtr(nu, x)`](stdtr) with respect to `nu` |
263//!
264//! ## Chi square distribution
265//!
266//! | Function    | Description                                           |
267//! | ----------- | ----------------------------------------------------- |
268//! | [`chdtr`]   | Cumulative distribution function                      |
269//! | [`chdtrc`]  | Complement of [`chdtr`]                               |
270//! | [`chdtri`]  | Inverse of [`chdtrc`]                                 |
271//! | [`chdtriv`] | Inverse of [`chdtr(v, x)`](chdtr) with respect to `v` |
272//!
273//! ## Noncentral chi square distribution
274//!
275//! | Function      | Description                                |
276//! | ------------- | ------------------------------------------ |
277//! | [`chndtr`]    | Cumulative distribution function           |
278//! | [`chndtri`]   | Inverse of [`chndtr`] with respect to `x`  |
279//! | [`chndtridf`] | Inverse of [`chndtr`] with respect to `df` |
280//! | [`chndtrinc`] | Inverse of [`chndtr`] with respect to `nc` |
281//!
282//! ## Kolmogorov distribution
283//!
284//! | Function       | Description                      |
285//! | -------------- | -------------------------------- |
286//! | [`kolmogorov`] | Survival function                |
287//! | [`kolmogp`]    | Derivative of [`kolmogorov`]     |
288//! | [`kolmogi`]    | Inverse of [`kolmogorov`]        |
289//! | [`kolmogc`]    | Complement of [`kolmogorov`]     |
290//! | [`kolmogci`]   | Inverse of [`kolmogc`]           |
291//!
292//! ## Kolmogorov-Smirnov distribution
293//!
294//! | Function      | Description                      |
295//! | ------------- | -------------------------------- |
296//! | [`smirnov`]   | Survival function                |
297//! | [`smirnovp`]  | Derivative of [`smirnov`]        |
298//! | [`smirnovi`]  | Inverse of [`smirnov`]           |
299//! | [`smirnovc`]  | Complement of [`smirnov`]        |
300//! | [`smirnovci`] | Inverse of [`smirnovc`]          |
301//!
302//! ## Box-Cox transformation
303//!
304//! | Function         | Description                       |
305//! | ---------------- | --------------------------------- |
306//! | [`boxcox`]       | Box-Cox transformation of $x$     |
307//! | [`boxcox1p`]     | Box-Cox transformation of $1 + x$ |
308//! | [`inv_boxcox`]   | Inverse of [`boxcox`]             |
309//! | [`inv_boxcox1p`] | Inverse of [`boxcox1p`]           |
310//!
311//! ## Sigmoidal functions
312//!
313//! | Function      | Description                               |
314//! | ------------- | ----------------------------------------- |
315//! | [`logit`]     | Logit function, $\ln \( \frac{x}{1-x} \)$ |
316//! | [`expit`]     | Expit function, $\frac{1}{1 + \exp(-x)}$  |
317//! | [`log_expit`] | Logarithm of [`expit`]                    |
318//!
319//! ## Cramér-von Mises
320//!
321//! | Function        | Description                                                         |
322//! | --------------- | ------------------------------------------------------------------- |
323//! | [`cdf_cvm_inf`] | CDF of the Cramér-von Mises test statistic (infinite sample limit)  |
324//! | [`cdf_cvm`]     | CDF of the Cramér-von Mises test statistic for a finite sample size |
325//!
326//! ## Wilcoxon signed-rank distribution
327//!
328//! | Function             | Description                                                 |
329//! | -------------------- | ----------------------------------------------------------- |
330//! | [`wilcoxon_pmf_all`] | Full probability mass function                              |
331//! | [`wilcoxon_cdf_all`] | Full cumulative distribution function                       |
332//! | [`wilcoxon_pmf`]     | Probability mass function, from [`wilcoxon_pmf_all`]        |
333//! | [`wilcoxon_cdf`]     | Cumulative distribution function, from [`wilcoxon_cdf_all`] |
334//! | [`wilcoxon_sf`]      | Survival function, from [`wilcoxon_cdf_all`]                |
335//!
336//! ## Multivariate normal distribution
337//!
338//! | Function                  | Description                                        |
339//! | ------------------------- | -------------------------------------------------- |
340//! | [`bivariate_normal_cdf`]  | CDF of the standard bivariate normal distribution  |
341//! | [`trivariate_normal_cdf`] | CDF of the standard trivariate normal distribution |
342//!
343//! ## Miscellaneous
344//!
345//! | Function           | Description                                    |
346//! | ------------------ | ---------------------------------------------- |
347//! | [`tukeylambdacdf`] | Tukey-Lambda cumulative distribution function  |
348//! | [`von_mises_cdf`]  | Von Mises cumulative distribution function     |
349//! | [`cosine_cdf`]     | Raised cosine cumulative distribution function |
350//! | [`cosine_invcdf`]  | Inverse of [`cosine_cdf`]                      |
351//! | [`owens_t`]        | Owen's T function                              |
352//!
353//! # Information Theory functions
354//!
355//! | Function         | Description                                                            |
356//! | ---------------- | ---------------------------------------------------------------------- |
357//! | [`entr`]         | Elementwise function for computing entropy, $H\[X\]$                   |
358//! | [`rel_entr`]     | Elementwise function for computing relative entropy, $H\[X \rvert Y\]$ |
359//! | [`kl_div`]       | Elementwise function for computing Kullback-Leibler divergence         |
360//! | [`huber`]        | Huber loss function, $L_\delta(r)$                                     |
361//! | [`pseudo_huber`] | Pseudo-Huber loss function, $\widetilde{L}_\delta(r)$                  |
362//!
363//! # Gamma and related functions
364//!
365//! | Function          | Description                                                       |
366//! | ----------------- | ----------------------------------------------------------------- |
367//! | [`gamma`]         | Gamma function, $\Gamma(z)$                                       |
368//! | [`gammaln`]       | Log-gamma function, $\ln\abs{\Gamma(z)}$                          |
369//! | [`loggamma`]      | Principal branch of $\ln \Gamma(z)$                               |
370//! | [`gammasgn`]      | Sign of [`gamma`], $\sgn(\Gamma(z))$                              |
371//! | [`gammainc`]      | Regularized lower incomplete gamma function $P(a,x) = 1 - Q(a,x)$ |
372//! | [`gammaincinv`]   | Inverse of [`gammainc`], $P^{-1}(a,y)$                            |
373//! | [`gammaincc`]     | Regularized upper incomplete gamma function $Q(a,x) = 1 - P(a,x)$ |
374//! | [`gammainccinv`]  | Inverse of [`gammaincc`], $Q^{-1}(a,y)$                           |
375//! | [`log_gammainc`]  | Log of [`gammainc`], $\ln P(a,x)$                                 |
376//! | [`log_gammaincc`] | Log of [`gammaincc`], $\ln Q(a,x)$                                |
377//! | [`beta`]          | Beta function, $\B(a,b) = {\Gamma(a)\Gamma(b) \over \Gamma(a+b)}$ |
378//! | [`betaln`]        | Log-Beta function, $\ln\abs{\B(a,b)}$                             |
379//! | [`betainc`]       | Regularized incomplete beta function, $\I_x(a,b)$                 |
380//! | [`betaincinv`]    | Inverse of [`betainc`], $\I_y^{-1}(a,b)$                          |
381//! | [`betaincc`]      | Complement of [`betainc`], $1 - \I_x(a,b)$                        |
382//! | [`betainccinv`]   | Inverse of [`betaincc`]                                           |
383//! | [`digamma`]       | The digamma function, $\psi(z)$                                   |
384//! | [`digammainv`]    | Inverse of [`digamma`], $\psi^{-1}(y)$                            |
385//! | [`trigamma`]      | The trigamma function, $\psi\'(z)$                                |
386//! | [`polygamma`]     | The polygamma function, $\psi^{(n)}(x)$                           |
387//! | [`multigammaln`]  | Log of multivariate gamma, sometimes called the generalized gamma |
388//! | [`rgamma`]        | Reciprocal of the gamma function, $\frac{1}{\Gamma(z)}$           |
389//! | [`pow_rising`]    | Rising factorial $\rpow x m = {\Gamma(x+m) \over \Gamma(x)}$      |
390//! | [`pow_falling`]   | Falling factorial $\fpow x m = {\Gamma(x+1) \over \Gamma(x+1-m)}$ |
391//!
392//! # Error function and Fresnel integrals
393//!
394//! | Function                   | Description                                                     |
395//! | -------------------------- | --------------------------------------------------------------- |
396//! | [`erf`]                    | Error function, $\erf(z)$                                       |
397//! | [`erfc`]                   | Complementary error function, $\erfc(z) = 1 - \erf(z)$          |
398//! | [`erfcx`]                  | Scaled complementary error function, $e^{z^2} \erfc(z)$         |
399//! | [`erfi`]                   | Imaginary error function $\erfi(z) = -i \erf(i z)$              |
400//! | [`erfinv`]                 | Inverse of [`erf`], $\erf^{-1}(z)$                              |
401//! | [`erfcinv`]                | Inverse of [`erfc`], $\erfc^{-1}(z) = \erf^{-1}(1 - z)$         |
402//! | [`erf_zeros`]              | Zeros (roots) of [`erf`]                                        |
403//! | [`wofz`]                   | Faddeeva function, $w(z) = e^{-z^2} \erfc(-iz)$                 |
404//! | [`dawsn`]                  | Dawson function $D(z) = \frac{\sqrt{\pi}}{2} e^{-z^2} \erfi(z)$ |
405//! | [`fresnel`]                | Fresnel integrals $S(z)$ and $C(z)$                             |
406//! | [`fresnel_zeros`]          | Zeros (roots) of Fresnel integrals $S(z)$ and $C(z)$            |
407//! | [`modified_fresnel_plus`]  | Modified Fresnel positive integrals                             |
408//! | [`modified_fresnel_minus`] | Modified Fresnel negative integrals                             |
409//! | [`voigt_profile`]          | Voigt profile                                                   |
410//!
411//! # Legendre functions
412//!
413//! | Function                      | Description                                                  |
414//! | ----------------------------- | ------------------------------------------------------------ |
415//! | [`legendre_p`]                | Legendre polynomial of the first kind, $P_n(z)$              |
416//! | [`legendre_p_all`]            | All Legendre polynomials of the first kind                   |
417//! | [`assoc_legendre_p`]          | Associated Legendre polynomial of the 1st kind, $P_n^m(z)$   |
418//! | [`assoc_legendre_p_all`]      | All associated Legendre polynomials of the 1st kind          |
419//! | [`assoc_legendre_p_norm`]     | Normalized associated Legendre polynomial                    |
420//! | [`assoc_legendre_p_norm_all`] | All normalized associated Legendre polynomials               |
421//! | [`sph_legendre_p`]            | Spherical Legendre polynomial of the first kind              |
422//! | [`sph_legendre_p_all`]        | All spherical Legendre polynomials of the first kind         |
423//! | [`sph_harm_y`]                | Spherical harmonics, $Y_n^m(\theta,\phi)$                    |
424//! | [`sph_harm_y_all`]            | All spherical harmonics                                      |
425//! | [`legendre_q_all`]       | All Legendre functions of the 2nd kind and derivatives            |
426//! | [`assoc_legendre_q_all`] | All associated Legendre functions of the 2nd kind and derivatives |
427//!
428//! # Orthogonal polynomials
429//!
430//! The following functions evaluate values of orthogonal polynomials:
431//!
432//! | Function                | Name                                 | Notation                   |
433//! | ----------------------- | ------------------------------------ | -------------------------- |
434//! | [`eval_jacobi`]         | Jacobi                               | $P_n^{(\alpha,\beta)}(z)$  |
435//! | [`eval_sh_jacobi`]      | Shifted Jacobi                       | $P_n^{*(\alpha,\beta)}(z)$ |
436//! | [`eval_gengegenbauer`]  | Generalized Gegenbauer               | $G_n^{(p,q)}(z)$           |
437//! | [`eval_legendre`]       | Legendre                             | $P_n(z)$                   |
438//! | [`eval_sh_legendre`]    | Shifted Legendre                     | $P_n^*(z)$                 |
439//! | [`eval_chebyshev_t`]    | Chebyshev (first kind)               | $T_n(z)$                   |
440//! | [`eval_chebyshev_u`]    | Chebyshev (second kind)              | $U_n(z)$                   |
441//! | [`eval_chebyshev_c`]    | Chebyshev (first kind) on $[-2, 2]$  | $C_n(z)$                   |
442//! | [`eval_chebyshev_s`]    | Chebyshev (second kind) on $[-2, 2]$ | $S_n(z)$                   |
443//! | [`eval_sh_chebyshev_t`] | Shifted Chebyshev (first kind)       | $T_n^*(z)$                 |
444//! | [`eval_sh_chebyshev_u`] | Shifted Chebyshev (second kind)      | $U_n^*(z)$                 |
445//! | [`eval_gegenbauer`]     | Gegenbauer / Ultraspherical          | $C_n^{(\alpha)}(z)$        |
446//! | [`eval_genlaguerre`]    | Generalized Laguerre                 | $L_n^{(\alpha)}(z)$        |
447//! | [`eval_laguerre`]       | Laguerre                             | $L_n(z)$                   |
448//! | [`eval_hermite_h`]      | Hermite (physicist's)                | $H_n(x)$                   |
449//! | [`eval_hermite_he`]     | Hermite (probabilist's)              | $He_n(x)$                  |
450//! | [`eval_hahn`]           | Hahn                                 | $Q_n(x;\alpha,\beta,N)$    |
451//!
452//! Note that [`eval_sh_jacobi`] differs from `scipy.special.eval_sh_jacobi`, which is
453//! [`eval_gengegenbauer`] here (scipy/scipy#18988).
454//!
455//! The following functions compute the nodes and weights of Gauss quadrature, i.e. the roots of
456//! these polynomials:
457//!
458//! | Function                 | Roots of                |
459//! | ------------------------ | ----------------------- |
460//! | [`roots_jacobi`]         | $P_n^{(\alpha,\beta)}$  |
461//! | [`roots_sh_jacobi`]      | $P_n^{*(\alpha,\beta)}$ |
462//! | [`roots_gengegenbauer`]  | $G_n^{(p,q)}$           |
463//! | [`roots_legendre`]       | $P_n$                   |
464//! | [`roots_sh_legendre`]    | $P_n^*$                 |
465//! | [`roots_chebyshev_t`]    | $T_n$                   |
466//! | [`roots_chebyshev_u`]    | $U_n$                   |
467//! | [`roots_chebyshev_c`]    | $C_n$                   |
468//! | [`roots_chebyshev_s`]    | $S_n$                   |
469//! | [`roots_sh_chebyshev_t`] | $T_n^*$                 |
470//! | [`roots_sh_chebyshev_u`] | $U_n^*$                 |
471//! | [`roots_gegenbauer`]     | $C_n^{(\alpha)}$        |
472//! | [`roots_genlaguerre`]    | $L_n^{(\alpha)}$        |
473//! | [`roots_laguerre`]       | $L_n$                   |
474//! | [`roots_hermite_h`]      | $H_n$                   |
475//! | [`roots_hermite_he`]     | $He_n$                  |
476//!
477//! # Hypergeometric functions
478//!
479//! | Function   | Description                             | Notation                                                     |
480//! | ---------- | --------------------------------------- | ------------------------------------------------------------ |
481//! | [`hyp0f0`] | Generalized hypergeometric function     | $_0F_0\left[ \middle\| z\right]$                             |
482//! | [`hyp1f0`] | Generalized hypergeometric function     | $_1F_0\left[a\middle\| z\right]$                             |
483//! | [`hyp0f1`] | Confluent hypergeometric limit function | $_0F_1\left[b\middle\| z\right]$                             |
484//! | [`hyp1f1`] | Confluent hypergeometric function       | $\hyp 1 1 a b z$                                             |
485//! | [`hyp1f2`] | Generalized hypergeometric function     | $\hyp 1 2 a {b_1\enspace b_2} z$                             |
486//! | [`hyp2f1`] | Gauss' hypergeometric function          | $\hyp 2 1 {a_1\enspace a_2} b z$                             |
487//! | [`hyp2f2`] | Generalized hypergeometric function     | $\hyp 2 2 {a_1\enspace a_2} {b_1\enspace b_2} z$             |
488//! | [`hyp3f2`] | Generalized hypergeometric function     | $\hyp 3 2 {a_1\enspace a_2\enspace a_3} {b_1\enspace b_2} z$ |
489//! | [`hyppfq`] | Generalized hypergeometric function     | $\hyp p q {a_1\enspace \cdots} {b_1\enspace \cdots} z$       |
490//! | [`hypu`]   | Confluent hypergeometric function       | $U(a_1,a_2,x)$                                               |
491//!
492//! # Parabolic cylinder functions
493//!
494//! | Function     | Description                                                        |
495//! | ------------ | ------------------------------------------------------------------ |
496//! | [`pbdn_seq`] | [`pbdv`] for the integer orders $0, \ldots, n$ and complex $z$     |
497//! | [`pbdv`]     | Parabolic cylinder function $D_v(x)$ and its derivative $D_v\'(x)$ |
498//! | [`pbdv_seq`] | [`pbdv`] for the orders $v - \lfloor v\rfloor, \ldots, v$          |
499//! | [`pbvv`]     | Parabolic cylinder function $V_v(x)$ and its derivative $V_v\'(x)$ |
500//! | [`pbvv_seq`] | [`pbvv`] for the orders $v - \lfloor v\rfloor, \ldots, v$          |
501//! | [`pbwa`]     | Parabolic cylinder function $W_a(x)$ and its derivative $W_a\'(x)$ |
502//!
503//! # Mathieu and related functions
504//!
505//! | Even                  | Odd                  | Description                                   |
506//! | --------------------- | -------------------- | --------------------------------------------- |
507//! | [`mathieu_a`]         | [`mathieu_b`]        | Characteristic value of the Mathieu functions |
508//! | [`mathieu_ce`]        | [`mathieu_se`]       | Mathieu functions                             |
509//! | [`mathieu_cem`]       | [`mathieu_sem`]      | Mathieu functions, of an angle in degrees     |
510//! | [`mathieu_modcem1`]   | [`mathieu_modsem1`]  | Modified Mathieu functions of the first kind  |
511//! | [`mathieu_modcem2`]   | [`mathieu_modsem2`]  | Modified Mathieu functions of the second kind |
512//! | [`mathieu_even_coef`] | [`mathieu_odd_coef`] | Fourier coefficients for Mathieu functions    |
513//!
514//! # Spheroidal wave functions
515//!
516//! | Function                 | Description                                           |
517//! | ------------------------ | ----------------------------------------------------- |
518//! | [`prolate_aswfa_nocv`]   | Prolate spheroidal angular function of the first kind |
519//! | [`prolate_radial1_nocv`] | Prolate spheroidal radial function of the first kind  |
520//! | [`prolate_radial2_nocv`] | Prolate spheroidal radial function of the second kind |
521//! | [`oblate_aswfa_nocv`]    | Oblate spheroidal angular function of the first kind  |
522//! | [`oblate_radial1_nocv`]  | Oblate spheroidal radial function of the first kind   |
523//! | [`oblate_radial2_nocv`]  | Oblate spheroidal radial function of the second kind  |
524//! | [`prolate_segv`]         | Characteristic value of prolate spheroidal function   |
525//! | [`oblate_segv`]          | Characteristic value of oblate spheroidal function    |
526//! | [`prolate_segv_seq`]     | Characteristic values of prolate spheroidal functions |
527//! | [`oblate_segv_seq`]      | Characteristic values of oblate spheroidal functions  |
528//!
529//! The following functions require pre-computed characteristic value:
530//!
531//! | Function            | Description                                           |
532//! | ------------------- | ----------------------------------------------------- |
533//! | [`prolate_aswfa`]   | Prolate spheroidal angular function of the first kind |
534//! | [`prolate_radial1`] | Prolate spheroidal radial function of the first kind  |
535//! | [`prolate_radial2`] | Prolate spheroidal radial function of the second kind |
536//! | [`oblate_aswfa`]    | Oblate spheroidal angular function of the first kind  |
537//! | [`oblate_radial1`]  | Oblate spheroidal radial function of the first kind   |
538//! | [`oblate_radial2`]  | Oblate spheroidal radial function of the second kind  |
539//!
540//! # Kelvin functions
541//!
542//! | Function   | Zeros            | Description                         |
543//! | ---------- | ---------------- | ----------------------------------- |
544//! | [`kelvin`] | [`kelvin_zeros`] | Kelvin functions as complex numbers |
545//! | [`ber`]    | [`ber_zeros`]    | Kelvin function $\ber(x)$           |
546//! | [`berp`]   | [`berp_zeros`]   | Derivative of [`ber`], $\ber\'(x)$  |
547//! | [`bei`]    | [`bei_zeros`]    | Kelvin function $\bei(x)$           |
548//! | [`beip`]   | [`beip_zeros`]   | Derivative of [`bei`], $\bei\'(x)$  |
549//! | [`ker`]    | [`ker_zeros`]    | Kelvin function $\ker(x)$           |
550//! | [`kerp`]   | [`kerp_zeros`]   | Derivative of [`ker`], $\ker\'(x)$  |
551//! | [`kei`]    | [`kei_zeros`]    | Kelvin function $\kei(x)$           |
552//! | [`keip`]   | [`keip_zeros`]   | Derivative of [`kei`], $\kei\'(x)$  |
553//!
554//! # Combinatorics
555//!
556//! | Function       | Description                                                              |
557//! | -------------- | ------------------------------------------------------------------------ |
558//! | [`comb`]       | $k$-combinations of $n$ things, $_nC_k = {n \choose k}$                  |
559//! | [`comb_rep`]   | $k$-combinations with replacement, $\big(\\!\\!{n \choose k}\\!\\!\big)$ |
560//! | [`perm`]       | $k$-permutations of $n$ things, $_nP_k = {n! \over (n-k)!}$              |
561//! | [`stirling2`]  | Stirling number of the second kind $S(n,k)$                              |
562//!
563//! # Factorials
564//!
565//! | Function                   | Description                               |
566//! | -------------------------- | ----------------------------------------- |
567//! | [`factorial`]              | Factorial $n!$                            |
568//! | [`factorial_checked`]      | [`factorial`] with overflow checking      |
569//! | [`multifactorial`]         | Multifactorial $n!_{(k)}$                 |
570//! | [`multifactorial_checked`] | [`multifactorial`] with overflow checking |
571//!
572//! # Exponential integrals
573//!
574//! | Function        | Description                                |
575//! | --------------- | ------------------------------------------ |
576//! | [`expn`]        | Generalized exponential integral $E_n(x)$  |
577//! | [`expi`]        | Exponential integral $Ei(x)$               |
578//! | [`exp1`]        | Exponential integral $E_1(x)$              |
579//! | [`scaled_exp1`] | Scaled exponential integral $x e^x E_1(x)$ |
580//!
581//! # Zeta functions
582//!
583//! | Function         | Description                                                |
584//! | ---------------- | ---------------------------------------------------------- |
585//! | [`zeta`]         | Hurwitz zeta function $\zeta(z,q)$ for real or complex $z$ |
586//! | [`riemann_zeta`] | Riemann zeta function $\zeta(z)$ for real or complex $z$   |
587//! | [`zetac`]        | $\zeta(x) - 1$ for real $x$                                |
588//!
589//! ## Harmonic numbers
590//!
591//! | Function                    | Description                                                 |
592//! | --------------------------- | ----------------------------------------------------------- |
593//! | [`gen_harmonic`]            | Generalized harmonic number $H_{n,a} = \sum_{i=1}^n i^{-a}$ |
594//! | [`normalized_gen_harmonic`] | Normalized partial sum $\sum_{i=j}^k i^{-a} / H_{n,a}$      |
595//!
596//! # Lambert W and related functions
597//!
598//! | Function        | Description           |
599//! | --------------- | --------------------- |
600//! | [`lambertw`]    | Lambert W function    |
601//! | [`wrightomega`] | Wright Omega function |
602//!
603//! # Other special functions
604//!
605//! | Function        | Description                                                  |
606//! | --------------- | ------------------------------------------------------------ |
607//! | [`agm`]         | Arithmetic-geometric mean of two scalars                     |
608//! | [`bernoulli`]   | Bernoulli numbers $B_0,\dotsc,B_{N-1}$                       |
609//! | [`binom`]       | Binomial coefficient $\binom{n}{k}$ for real input           |
610//! | [`diric`]       | Periodic sinc function, also called the Dirichlet kernel     |
611//! | [`euler`]       | Euler numbers $E_0,\dotsc,E_{N-1}$                           |
612//! | [`sici`]        | Sine and cosine integrals $\Si(z)$ and $\Ci(z)$              |
613//! | [`shichi`]      | Hyperbolic sine and cosine integrals $\Shi(z)$ and $\Chi(z)$ |
614//! | [`softmax`]     | Softmax function                                             |
615//! | [`log_softmax`] | Logarithm of the softmax function                            |
616//! | [`spence`]      | Spence's function, also known as the dilogarithm             |
617//! | [`softplus`]    | $\ln(1 + e^x)$                                               |
618//! | [`log1mexp`]    | $\ln(1 - e^x)$                                               |
619//!
620//! # Convenience functions
621//!
622//! | Function       | Description                                         |
623//! | -------------- | --------------------------------------------------- |
624//! | [`cbrt`]       | $\sqrt\[3\]{x}$                                     |
625//! | [`exp10`]      | $10^x$                                              |
626//! | [`exp2`]       | $2^x$                                               |
627//! | [`radian`]     | Convert from degrees to radians                     |
628//! | [`cosdg`]      | Cosine of an angle in degrees                       |
629//! | [`sindg`]      | Sine of an angle in degrees                         |
630//! | [`tandg`]      | Tangent of an angle in degrees                      |
631//! | [`cotdg`]      | Cotangent of an angle in degrees                    |
632//! | [`cospi`]      | $\cos(\pi z)$                                       |
633//! | [`sinpi`]      | $\sin(\pi z)$                                       |
634//! | [`log1p`]      | $\ln(1+z)$                                          |
635//! | [`log1pmx`]    | $\ln(1+x) - x$                                      |
636//! | [`expm1`]      | $e^x - 1$                                           |
637//! | [`cosm1`]      | $\cos(x) - 1$                                       |
638//! | [`powm1`]      | $x^y - 1$                                           |
639//! | [`round`]      | Round to nearest or even integer-valued float       |
640//! | [`xlogy`]      | $x \ln(y)$ or $0$ if $x = 0$                        |
641//! | [`xlog1py`]    | $x \ln(1+y)$ or $0$ if $x = 0$                      |
642//! | [`logaddexp`]  | $\ln(e^x + e^y)$                                    |
643//! | [`logaddexp2`] | $\log_2(2^x + 2^y)$                                 |
644//! | [`logsumexp`]  | $\ln \sum e^{x_i}$                                  |
645//! | [`exprel`]     | Relative error exponential, $e^x - 1 \over x$       |
646//! | [`sinc`]       | Normalized sinc function, $\sin(\pi x) \over \pi x$ |
647//!
648
649#![forbid(unsafe_code)]
650#![warn(
651    missing_debug_implementations,
652    missing_docs,
653    rust_2018_idioms,
654    unreachable_pub
655)]
656#![warn(clippy::pedantic)]
657// Allow the common porting idioms, to keep the Rust close to the C++
658#![allow(
659    clippy::doc_markdown,
660    clippy::many_single_char_names,
661    clippy::similar_names,
662    // exact comparisons such as `x == 0.0` and `x == x.floor()` are intended
663    clippy::float_cmp,
664    // `as` casts follow the C++ conversions (see the local notes for edge cases)
665    clippy::cast_possible_truncation,
666    clippy::cast_precision_loss,
667    clippy::cast_sign_loss,
668    // coefficients are copied verbatim, so that they can be diffed against the C++
669    clippy::excessive_precision,
670    clippy::unreadable_literal,
671    // functions keep the size, signature, and branch order of the C++
672    clippy::too_many_arguments,
673    clippy::too_many_lines,
674    clippy::if_not_else,
675    // `!(a > b)` also catches NaN, like in the C++
676    clippy::neg_cmp_op_on_partial_ord,
677    // `f64::midpoint` can change results, and it also flags factors like `0.5 * (k + 0.5)`
678    clippy::manual_midpoint
679)]
680
681mod ext;
682mod numpy;
683mod scipy_special;
684mod utils;
685mod xsf;
686
687pub(crate) mod sealed {
688    pub trait Sealed {}
689    impl Sealed for f32 {}
690    impl Sealed for f64 {}
691    impl Sealed for u8 {}
692    impl Sealed for u16 {}
693    impl Sealed for u32 {}
694    impl Sealed for u64 {}
695    impl Sealed for u128 {}
696    impl Sealed for usize {}
697    impl Sealed for num_complex::Complex<f64> {}
698}
699
700pub use ext::*;
701pub use numpy::*;
702pub use scipy_special::*;
703pub use xsf::*;