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::*;