Coverage for /usr/lib/python3/dist-packages/scipy/special/_add_newdocs.py: 99%
270 statements
« prev ^ index » next coverage.py v7.9.1, created at 2025-06-14 15:55 +0200
1# Docstrings for generated ufuncs
2#
3# The syntax is designed to look like the function add_newdoc is being
4# called from numpy.lib, but in this file add_newdoc puts the
5# docstrings in a dictionary. This dictionary is used in
6# _generate_pyx.py to generate the docstrings for the ufuncs in
7# scipy.special at the C level when the ufuncs are created at compile
8# time.
10docdict: dict[str, str] = {}
13def get(name):
14 return docdict.get(name)
17def add_newdoc(name, doc):
18 docdict[name] = doc
21add_newdoc("_sf_error_test_function",
22 """
23 Private function; do not use.
24 """)
27add_newdoc("_cosine_cdf",
28 """
29 _cosine_cdf(x)
31 Cumulative distribution function (CDF) of the cosine distribution::
33 { 0, x < -pi
34 cdf(x) = { (pi + x + sin(x))/(2*pi), -pi <= x <= pi
35 { 1, x > pi
37 Parameters
38 ----------
39 x : array_like
40 `x` must contain real numbers.
42 Returns
43 -------
44 scalar or ndarray
45 The cosine distribution CDF evaluated at `x`.
47 """)
49add_newdoc("_cosine_invcdf",
50 """
51 _cosine_invcdf(p)
53 Inverse of the cumulative distribution function (CDF) of the cosine
54 distribution.
56 The CDF of the cosine distribution is::
58 cdf(x) = (pi + x + sin(x))/(2*pi)
60 This function computes the inverse of cdf(x).
62 Parameters
63 ----------
64 p : array_like
65 `p` must contain real numbers in the interval ``0 <= p <= 1``.
66 `nan` is returned for values of `p` outside the interval [0, 1].
68 Returns
69 -------
70 scalar or ndarray
71 The inverse of the cosine distribution CDF evaluated at `p`.
73 """)
75add_newdoc("sph_harm",
76 r"""
77 sph_harm(m, n, theta, phi, out=None)
79 Compute spherical harmonics.
81 The spherical harmonics are defined as
83 .. math::
85 Y^m_n(\theta,\phi) = \sqrt{\frac{2n+1}{4\pi} \frac{(n-m)!}{(n+m)!}}
86 e^{i m \theta} P^m_n(\cos(\phi))
88 where :math:`P_n^m` are the associated Legendre functions; see `lpmv`.
90 Parameters
91 ----------
92 m : array_like
93 Order of the harmonic (int); must have ``|m| <= n``.
94 n : array_like
95 Degree of the harmonic (int); must have ``n >= 0``. This is
96 often denoted by ``l`` (lower case L) in descriptions of
97 spherical harmonics.
98 theta : array_like
99 Azimuthal (longitudinal) coordinate; must be in ``[0, 2*pi]``.
100 phi : array_like
101 Polar (colatitudinal) coordinate; must be in ``[0, pi]``.
102 out : ndarray, optional
103 Optional output array for the function values
105 Returns
106 -------
107 y_mn : complex scalar or ndarray
108 The harmonic :math:`Y^m_n` sampled at ``theta`` and ``phi``.
110 Notes
111 -----
112 There are different conventions for the meanings of the input
113 arguments ``theta`` and ``phi``. In SciPy ``theta`` is the
114 azimuthal angle and ``phi`` is the polar angle. It is common to
115 see the opposite convention, that is, ``theta`` as the polar angle
116 and ``phi`` as the azimuthal angle.
118 Note that SciPy's spherical harmonics include the Condon-Shortley
119 phase [2]_ because it is part of `lpmv`.
121 With SciPy's conventions, the first several spherical harmonics
122 are
124 .. math::
126 Y_0^0(\theta, \phi) &= \frac{1}{2} \sqrt{\frac{1}{\pi}} \\
127 Y_1^{-1}(\theta, \phi) &= \frac{1}{2} \sqrt{\frac{3}{2\pi}}
128 e^{-i\theta} \sin(\phi) \\
129 Y_1^0(\theta, \phi) &= \frac{1}{2} \sqrt{\frac{3}{\pi}}
130 \cos(\phi) \\
131 Y_1^1(\theta, \phi) &= -\frac{1}{2} \sqrt{\frac{3}{2\pi}}
132 e^{i\theta} \sin(\phi).
134 References
135 ----------
136 .. [1] Digital Library of Mathematical Functions, 14.30.
137 https://dlmf.nist.gov/14.30
138 .. [2] https://en.wikipedia.org/wiki/Spherical_harmonics#Condon.E2.80.93Shortley_phase
139 """)
141add_newdoc("_ellip_harm",
142 """
143 Internal function, use `ellip_harm` instead.
144 """)
146add_newdoc("_ellip_norm",
147 """
148 Internal function, use `ellip_norm` instead.
149 """)
151add_newdoc("_lambertw",
152 """
153 Internal function, use `lambertw` instead.
154 """)
156add_newdoc("voigt_profile",
157 r"""
158 voigt_profile(x, sigma, gamma, out=None)
160 Voigt profile.
162 The Voigt profile is a convolution of a 1-D Normal distribution with
163 standard deviation ``sigma`` and a 1-D Cauchy distribution with half-width at
164 half-maximum ``gamma``.
166 If ``sigma = 0``, PDF of Cauchy distribution is returned.
167 Conversely, if ``gamma = 0``, PDF of Normal distribution is returned.
168 If ``sigma = gamma = 0``, the return value is ``Inf`` for ``x = 0``, and ``0`` for all other ``x``.
170 Parameters
171 ----------
172 x : array_like
173 Real argument
174 sigma : array_like
175 The standard deviation of the Normal distribution part
176 gamma : array_like
177 The half-width at half-maximum of the Cauchy distribution part
178 out : ndarray, optional
179 Optional output array for the function values
181 Returns
182 -------
183 scalar or ndarray
184 The Voigt profile at the given arguments
186 Notes
187 -----
188 It can be expressed in terms of Faddeeva function
190 .. math:: V(x; \sigma, \gamma) = \frac{Re[w(z)]}{\sigma\sqrt{2\pi}},
191 .. math:: z = \frac{x + i\gamma}{\sqrt{2}\sigma}
193 where :math:`w(z)` is the Faddeeva function.
195 See Also
196 --------
197 wofz : Faddeeva function
199 References
200 ----------
201 .. [1] https://en.wikipedia.org/wiki/Voigt_profile
203 Examples
204 --------
205 Calculate the function at point 2 for ``sigma=1`` and ``gamma=1``.
207 >>> from scipy.special import voigt_profile
208 >>> import numpy as np
209 >>> import matplotlib.pyplot as plt
210 >>> voigt_profile(2, 1., 1.)
211 0.09071519942627544
213 Calculate the function at several points by providing a NumPy array
214 for `x`.
216 >>> values = np.array([-2., 0., 5])
217 >>> voigt_profile(values, 1., 1.)
218 array([0.0907152 , 0.20870928, 0.01388492])
220 Plot the function for different parameter sets.
222 >>> fig, ax = plt.subplots(figsize=(8, 8))
223 >>> x = np.linspace(-10, 10, 500)
224 >>> parameters_list = [(1.5, 0., "solid"), (1.3, 0.5, "dashed"),
225 ... (0., 1.8, "dotted"), (1., 1., "dashdot")]
226 >>> for params in parameters_list:
227 ... sigma, gamma, linestyle = params
228 ... voigt = voigt_profile(x, sigma, gamma)
229 ... ax.plot(x, voigt, label=rf"$\sigma={sigma},\, \gamma={gamma}$",
230 ... ls=linestyle)
231 >>> ax.legend()
232 >>> plt.show()
234 Verify visually that the Voigt profile indeed arises as the convolution
235 of a normal and a Cauchy distribution.
237 >>> from scipy.signal import convolve
238 >>> x, dx = np.linspace(-10, 10, 500, retstep=True)
239 >>> def gaussian(x, sigma):
240 ... return np.exp(-0.5 * x**2/sigma**2)/(sigma * np.sqrt(2*np.pi))
241 >>> def cauchy(x, gamma):
242 ... return gamma/(np.pi * (np.square(x)+gamma**2))
243 >>> sigma = 2
244 >>> gamma = 1
245 >>> gauss_profile = gaussian(x, sigma)
246 >>> cauchy_profile = cauchy(x, gamma)
247 >>> convolved = dx * convolve(cauchy_profile, gauss_profile, mode="same")
248 >>> voigt = voigt_profile(x, sigma, gamma)
249 >>> fig, ax = plt.subplots(figsize=(8, 8))
250 >>> ax.plot(x, gauss_profile, label="Gauss: $G$", c='b')
251 >>> ax.plot(x, cauchy_profile, label="Cauchy: $C$", c='y', ls="dashed")
252 >>> xx = 0.5*(x[1:] + x[:-1]) # midpoints
253 >>> ax.plot(xx, convolved[1:], label="Convolution: $G * C$", ls='dashdot',
254 ... c='k')
255 >>> ax.plot(x, voigt, label="Voigt", ls='dotted', c='r')
256 >>> ax.legend()
257 >>> plt.show()
258 """)
260add_newdoc("wrightomega",
261 r"""
262 wrightomega(z, out=None)
264 Wright Omega function.
266 Defined as the solution to
268 .. math::
270 \omega + \log(\omega) = z
272 where :math:`\log` is the principal branch of the complex logarithm.
274 Parameters
275 ----------
276 z : array_like
277 Points at which to evaluate the Wright Omega function
278 out : ndarray, optional
279 Optional output array for the function values
281 Returns
282 -------
283 omega : scalar or ndarray
284 Values of the Wright Omega function
286 Notes
287 -----
288 .. versionadded:: 0.19.0
290 The function can also be defined as
292 .. math::
294 \omega(z) = W_{K(z)}(e^z)
296 where :math:`K(z) = \lceil (\Im(z) - \pi)/(2\pi) \rceil` is the
297 unwinding number and :math:`W` is the Lambert W function.
299 The implementation here is taken from [1]_.
301 See Also
302 --------
303 lambertw : The Lambert W function
305 References
306 ----------
307 .. [1] Lawrence, Corless, and Jeffrey, "Algorithm 917: Complex
308 Double-Precision Evaluation of the Wright :math:`\omega`
309 Function." ACM Transactions on Mathematical Software,
310 2012. :doi:`10.1145/2168773.2168779`.
312 Examples
313 --------
314 >>> import numpy as np
315 >>> from scipy.special import wrightomega, lambertw
317 >>> wrightomega([-2, -1, 0, 1, 2])
318 array([0.12002824, 0.27846454, 0.56714329, 1. , 1.5571456 ])
320 Complex input:
322 >>> wrightomega(3 + 5j)
323 (1.5804428632097158+3.8213626783287937j)
325 Verify that ``wrightomega(z)`` satisfies ``w + log(w) = z``:
327 >>> w = -5 + 4j
328 >>> wrightomega(w + np.log(w))
329 (-5+4j)
331 Verify the connection to ``lambertw``:
333 >>> z = 0.5 + 3j
334 >>> wrightomega(z)
335 (0.0966015889280649+1.4937828458191993j)
336 >>> lambertw(np.exp(z))
337 (0.09660158892806493+1.4937828458191993j)
339 >>> z = 0.5 + 4j
340 >>> wrightomega(z)
341 (-0.3362123489037213+2.282986001579032j)
342 >>> lambertw(np.exp(z), k=1)
343 (-0.33621234890372115+2.282986001579032j)
344 """)
347add_newdoc("agm",
348 """
349 agm(a, b, out=None)
351 Compute the arithmetic-geometric mean of `a` and `b`.
353 Start with a_0 = a and b_0 = b and iteratively compute::
355 a_{n+1} = (a_n + b_n)/2
356 b_{n+1} = sqrt(a_n*b_n)
358 a_n and b_n converge to the same limit as n increases; their common
359 limit is agm(a, b).
361 Parameters
362 ----------
363 a, b : array_like
364 Real values only. If the values are both negative, the result
365 is negative. If one value is negative and the other is positive,
366 `nan` is returned.
367 out : ndarray, optional
368 Optional output array for the function values
370 Returns
371 -------
372 scalar or ndarray
373 The arithmetic-geometric mean of `a` and `b`.
375 Examples
376 --------
377 >>> import numpy as np
378 >>> from scipy.special import agm
379 >>> a, b = 24.0, 6.0
380 >>> agm(a, b)
381 13.458171481725614
383 Compare that result to the iteration:
385 >>> while a != b:
386 ... a, b = (a + b)/2, np.sqrt(a*b)
387 ... print("a = %19.16f b=%19.16f" % (a, b))
388 ...
389 a = 15.0000000000000000 b=12.0000000000000000
390 a = 13.5000000000000000 b=13.4164078649987388
391 a = 13.4582039324993694 b=13.4581390309909850
392 a = 13.4581714817451772 b=13.4581714817060547
393 a = 13.4581714817256159 b=13.4581714817256159
395 When array-like arguments are given, broadcasting applies:
397 >>> a = np.array([[1.5], [3], [6]]) # a has shape (3, 1).
398 >>> b = np.array([6, 12, 24, 48]) # b has shape (4,).
399 >>> agm(a, b)
400 array([[ 3.36454287, 5.42363427, 9.05798751, 15.53650756],
401 [ 4.37037309, 6.72908574, 10.84726853, 18.11597502],
402 [ 6. , 8.74074619, 13.45817148, 21.69453707]])
403 """)
405add_newdoc("airy",
406 r"""
407 airy(z, out=None)
409 Airy functions and their derivatives.
411 Parameters
412 ----------
413 z : array_like
414 Real or complex argument.
415 out : tuple of ndarray, optional
416 Optional output arrays for the function values
418 Returns
419 -------
420 Ai, Aip, Bi, Bip : 4-tuple of scalar or ndarray
421 Airy functions Ai and Bi, and their derivatives Aip and Bip.
423 Notes
424 -----
425 The Airy functions Ai and Bi are two independent solutions of
427 .. math:: y''(x) = x y(x).
429 For real `z` in [-10, 10], the computation is carried out by calling
430 the Cephes [1]_ `airy` routine, which uses power series summation
431 for small `z` and rational minimax approximations for large `z`.
433 Outside this range, the AMOS [2]_ `zairy` and `zbiry` routines are
434 employed. They are computed using power series for :math:`|z| < 1` and
435 the following relations to modified Bessel functions for larger `z`
436 (where :math:`t \equiv 2 z^{3/2}/3`):
438 .. math::
440 Ai(z) = \frac{1}{\pi \sqrt{3}} K_{1/3}(t)
442 Ai'(z) = -\frac{z}{\pi \sqrt{3}} K_{2/3}(t)
444 Bi(z) = \sqrt{\frac{z}{3}} \left(I_{-1/3}(t) + I_{1/3}(t) \right)
446 Bi'(z) = \frac{z}{\sqrt{3}} \left(I_{-2/3}(t) + I_{2/3}(t)\right)
448 See also
449 --------
450 airye : exponentially scaled Airy functions.
452 References
453 ----------
454 .. [1] Cephes Mathematical Functions Library,
455 http://www.netlib.org/cephes/
456 .. [2] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
457 of a Complex Argument and Nonnegative Order",
458 http://netlib.org/amos/
460 Examples
461 --------
462 Compute the Airy functions on the interval [-15, 5].
464 >>> import numpy as np
465 >>> from scipy import special
466 >>> x = np.linspace(-15, 5, 201)
467 >>> ai, aip, bi, bip = special.airy(x)
469 Plot Ai(x) and Bi(x).
471 >>> import matplotlib.pyplot as plt
472 >>> plt.plot(x, ai, 'r', label='Ai(x)')
473 >>> plt.plot(x, bi, 'b--', label='Bi(x)')
474 >>> plt.ylim(-0.5, 1.0)
475 >>> plt.grid()
476 >>> plt.legend(loc='upper left')
477 >>> plt.show()
479 """)
481add_newdoc("airye",
482 """
483 airye(z, out=None)
485 Exponentially scaled Airy functions and their derivatives.
487 Scaling::
489 eAi = Ai * exp(2.0/3.0*z*sqrt(z))
490 eAip = Aip * exp(2.0/3.0*z*sqrt(z))
491 eBi = Bi * exp(-abs(2.0/3.0*(z*sqrt(z)).real))
492 eBip = Bip * exp(-abs(2.0/3.0*(z*sqrt(z)).real))
494 Parameters
495 ----------
496 z : array_like
497 Real or complex argument.
498 out : tuple of ndarray, optional
499 Optional output arrays for the function values
501 Returns
502 -------
503 eAi, eAip, eBi, eBip : 4-tuple of scalar or ndarray
504 Exponentially scaled Airy functions eAi and eBi, and their derivatives
505 eAip and eBip
507 Notes
508 -----
509 Wrapper for the AMOS [1]_ routines `zairy` and `zbiry`.
511 See also
512 --------
513 airy
515 References
516 ----------
517 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
518 of a Complex Argument and Nonnegative Order",
519 http://netlib.org/amos/
521 Examples
522 --------
523 We can compute exponentially scaled Airy functions and their derivatives:
525 >>> import numpy as np
526 >>> from scipy.special import airye
527 >>> import matplotlib.pyplot as plt
528 >>> z = np.linspace(0, 50, 500)
529 >>> eAi, eAip, eBi, eBip = airye(z)
530 >>> f, ax = plt.subplots(2, 1, sharex=True)
531 >>> for ind, data in enumerate([[eAi, eAip, ["eAi", "eAip"]],
532 ... [eBi, eBip, ["eBi", "eBip"]]]):
533 ... ax[ind].plot(z, data[0], "-r", z, data[1], "-b")
534 ... ax[ind].legend(data[2])
535 ... ax[ind].grid(True)
536 >>> plt.show()
538 We can compute these using usual non-scaled Airy functions by:
540 >>> from scipy.special import airy
541 >>> Ai, Aip, Bi, Bip = airy(z)
542 >>> np.allclose(eAi, Ai * np.exp(2.0 / 3.0 * z * np.sqrt(z)))
543 True
544 >>> np.allclose(eAip, Aip * np.exp(2.0 / 3.0 * z * np.sqrt(z)))
545 True
546 >>> np.allclose(eBi, Bi * np.exp(-abs(np.real(2.0 / 3.0 * z * np.sqrt(z)))))
547 True
548 >>> np.allclose(eBip, Bip * np.exp(-abs(np.real(2.0 / 3.0 * z * np.sqrt(z)))))
549 True
551 Comparing non-scaled and exponentially scaled ones, the usual non-scaled
552 function quickly underflows for large values, whereas the exponentially
553 scaled function does not.
555 >>> airy(200)
556 (0.0, 0.0, nan, nan)
557 >>> airye(200)
558 (0.07501041684381093, -1.0609012305109042, 0.15003188417418148, 2.1215836725571093)
560 """)
562add_newdoc("bdtr",
563 r"""
564 bdtr(k, n, p, out=None)
566 Binomial distribution cumulative distribution function.
568 Sum of the terms 0 through `floor(k)` of the Binomial probability density.
570 .. math::
571 \mathrm{bdtr}(k, n, p) = \sum_{j=0}^{\lfloor k \rfloor} {{n}\choose{j}} p^j (1-p)^{n-j}
573 Parameters
574 ----------
575 k : array_like
576 Number of successes (double), rounded down to the nearest integer.
577 n : array_like
578 Number of events (int).
579 p : array_like
580 Probability of success in a single event (float).
581 out : ndarray, optional
582 Optional output array for the function values
584 Returns
585 -------
586 y : scalar or ndarray
587 Probability of `floor(k)` or fewer successes in `n` independent events with
588 success probabilities of `p`.
590 Notes
591 -----
592 The terms are not summed directly; instead the regularized incomplete beta
593 function is employed, according to the formula,
595 .. math::
596 \mathrm{bdtr}(k, n, p) = I_{1 - p}(n - \lfloor k \rfloor, \lfloor k \rfloor + 1).
598 Wrapper for the Cephes [1]_ routine `bdtr`.
600 References
601 ----------
602 .. [1] Cephes Mathematical Functions Library,
603 http://www.netlib.org/cephes/
605 """)
607add_newdoc("bdtrc",
608 r"""
609 bdtrc(k, n, p, out=None)
611 Binomial distribution survival function.
613 Sum of the terms `floor(k) + 1` through `n` of the binomial probability
614 density,
616 .. math::
617 \mathrm{bdtrc}(k, n, p) = \sum_{j=\lfloor k \rfloor +1}^n {{n}\choose{j}} p^j (1-p)^{n-j}
619 Parameters
620 ----------
621 k : array_like
622 Number of successes (double), rounded down to nearest integer.
623 n : array_like
624 Number of events (int)
625 p : array_like
626 Probability of success in a single event.
627 out : ndarray, optional
628 Optional output array for the function values
630 Returns
631 -------
632 y : scalar or ndarray
633 Probability of `floor(k) + 1` or more successes in `n` independent
634 events with success probabilities of `p`.
636 See also
637 --------
638 bdtr
639 betainc
641 Notes
642 -----
643 The terms are not summed directly; instead the regularized incomplete beta
644 function is employed, according to the formula,
646 .. math::
647 \mathrm{bdtrc}(k, n, p) = I_{p}(\lfloor k \rfloor + 1, n - \lfloor k \rfloor).
649 Wrapper for the Cephes [1]_ routine `bdtrc`.
651 References
652 ----------
653 .. [1] Cephes Mathematical Functions Library,
654 http://www.netlib.org/cephes/
656 """)
658add_newdoc("bdtri",
659 r"""
660 bdtri(k, n, y, out=None)
662 Inverse function to `bdtr` with respect to `p`.
664 Finds the event probability `p` such that the sum of the terms 0 through
665 `k` of the binomial probability density is equal to the given cumulative
666 probability `y`.
668 Parameters
669 ----------
670 k : array_like
671 Number of successes (float), rounded down to the nearest integer.
672 n : array_like
673 Number of events (float)
674 y : array_like
675 Cumulative probability (probability of `k` or fewer successes in `n`
676 events).
677 out : ndarray, optional
678 Optional output array for the function values
680 Returns
681 -------
682 p : scalar or ndarray
683 The event probability such that `bdtr(\lfloor k \rfloor, n, p) = y`.
685 See also
686 --------
687 bdtr
688 betaincinv
690 Notes
691 -----
692 The computation is carried out using the inverse beta integral function
693 and the relation,::
695 1 - p = betaincinv(n - k, k + 1, y).
697 Wrapper for the Cephes [1]_ routine `bdtri`.
699 References
700 ----------
701 .. [1] Cephes Mathematical Functions Library,
702 http://www.netlib.org/cephes/
703 """)
705add_newdoc("bdtrik",
706 """
707 bdtrik(y, n, p, out=None)
709 Inverse function to `bdtr` with respect to `k`.
711 Finds the number of successes `k` such that the sum of the terms 0 through
712 `k` of the Binomial probability density for `n` events with probability
713 `p` is equal to the given cumulative probability `y`.
715 Parameters
716 ----------
717 y : array_like
718 Cumulative probability (probability of `k` or fewer successes in `n`
719 events).
720 n : array_like
721 Number of events (float).
722 p : array_like
723 Success probability (float).
724 out : ndarray, optional
725 Optional output array for the function values
727 Returns
728 -------
729 k : scalar or ndarray
730 The number of successes `k` such that `bdtr(k, n, p) = y`.
732 See also
733 --------
734 bdtr
736 Notes
737 -----
738 Formula 26.5.24 of [1]_ is used to reduce the binomial distribution to the
739 cumulative incomplete beta distribution.
741 Computation of `k` involves a search for a value that produces the desired
742 value of `y`. The search relies on the monotonicity of `y` with `k`.
744 Wrapper for the CDFLIB [2]_ Fortran routine `cdfbin`.
746 References
747 ----------
748 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
749 Handbook of Mathematical Functions with Formulas,
750 Graphs, and Mathematical Tables. New York: Dover, 1972.
751 .. [2] Barry Brown, James Lovato, and Kathy Russell,
752 CDFLIB: Library of Fortran Routines for Cumulative Distribution
753 Functions, Inverses, and Other Parameters.
755 """)
757add_newdoc("bdtrin",
758 """
759 bdtrin(k, y, p, out=None)
761 Inverse function to `bdtr` with respect to `n`.
763 Finds the number of events `n` such that the sum of the terms 0 through
764 `k` of the Binomial probability density for events with probability `p` is
765 equal to the given cumulative probability `y`.
767 Parameters
768 ----------
769 k : array_like
770 Number of successes (float).
771 y : array_like
772 Cumulative probability (probability of `k` or fewer successes in `n`
773 events).
774 p : array_like
775 Success probability (float).
776 out : ndarray, optional
777 Optional output array for the function values
779 Returns
780 -------
781 n : scalar or ndarray
782 The number of events `n` such that `bdtr(k, n, p) = y`.
784 See also
785 --------
786 bdtr
788 Notes
789 -----
790 Formula 26.5.24 of [1]_ is used to reduce the binomial distribution to the
791 cumulative incomplete beta distribution.
793 Computation of `n` involves a search for a value that produces the desired
794 value of `y`. The search relies on the monotonicity of `y` with `n`.
796 Wrapper for the CDFLIB [2]_ Fortran routine `cdfbin`.
798 References
799 ----------
800 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
801 Handbook of Mathematical Functions with Formulas,
802 Graphs, and Mathematical Tables. New York: Dover, 1972.
803 .. [2] Barry Brown, James Lovato, and Kathy Russell,
804 CDFLIB: Library of Fortran Routines for Cumulative Distribution
805 Functions, Inverses, and Other Parameters.
806 """)
808add_newdoc(
809 "binom",
810 r"""
811 binom(x, y, out=None)
813 Binomial coefficient considered as a function of two real variables.
815 For real arguments, the binomial coefficient is defined as
817 .. math::
819 \binom{x}{y} = \frac{\Gamma(x + 1)}{\Gamma(y + 1)\Gamma(x - y + 1)} =
820 \frac{1}{(x + 1)\mathrm{B}(x - y + 1, y + 1)}
822 Where :math:`\Gamma` is the Gamma function (`gamma`) and :math:`\mathrm{B}`
823 is the Beta function (`beta`) [1]_.
825 Parameters
826 ----------
827 x, y: array_like
828 Real arguments to :math:`\binom{x}{y}`.
829 out : ndarray, optional
830 Optional output array for the function values
832 Returns
833 -------
834 scalar or ndarray
835 Value of binomial coefficient.
837 See Also
838 --------
839 comb : The number of combinations of N things taken k at a time.
841 Notes
842 -----
843 The Gamma function has poles at non-positive integers and tends to either
844 positive or negative infinity depending on the direction on the real line
845 from which a pole is approached. When considered as a function of two real
846 variables, :math:`\binom{x}{y}` is thus undefined when `x` is a negative
847 integer. `binom` returns ``nan`` when ``x`` is a negative integer. This
848 is the case even when ``x`` is a negative integer and ``y`` an integer,
849 contrary to the usual convention for defining :math:`\binom{n}{k}` when it
850 is considered as a function of two integer variables.
852 References
853 ----------
854 .. [1] https://en.wikipedia.org/wiki/Binomial_coefficient
856 Examples
857 --------
858 The following examples illustrate the ways in which `binom` differs from
859 the function `comb`.
861 >>> from scipy.special import binom, comb
863 When ``exact=False`` and ``x`` and ``y`` are both positive, `comb` calls
864 `binom` internally.
866 >>> x, y = 3, 2
867 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
868 (3.0, 3.0, 3)
870 For larger values, `comb` with ``exact=True`` no longer agrees
871 with `binom`.
873 >>> x, y = 43, 23
874 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
875 (960566918219.9999, 960566918219.9999, 960566918220)
877 `binom` returns ``nan`` when ``x`` is a negative integer, but is otherwise
878 defined for negative arguments. `comb` returns 0 whenever one of ``x`` or
879 ``y`` is negative or ``x`` is less than ``y``.
881 >>> x, y = -3, 2
882 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
883 (nan, 0.0, 0)
885 >>> x, y = -3.1, 2.2
886 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
887 (18.714147876804432, 0.0, 0)
889 >>> x, y = 2.2, 3.1
890 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
891 (0.037399983365134115, 0.0, 0)
892 """
893)
895add_newdoc("btdtria",
896 r"""
897 btdtria(p, b, x, out=None)
899 Inverse of `btdtr` with respect to `a`.
901 This is the inverse of the beta cumulative distribution function, `btdtr`,
902 considered as a function of `a`, returning the value of `a` for which
903 `btdtr(a, b, x) = p`, or
905 .. math::
906 p = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
908 Parameters
909 ----------
910 p : array_like
911 Cumulative probability, in [0, 1].
912 b : array_like
913 Shape parameter (`b` > 0).
914 x : array_like
915 The quantile, in [0, 1].
916 out : ndarray, optional
917 Optional output array for the function values
919 Returns
920 -------
921 a : scalar or ndarray
922 The value of the shape parameter `a` such that `btdtr(a, b, x) = p`.
924 See Also
925 --------
926 btdtr : Cumulative distribution function of the beta distribution.
927 btdtri : Inverse with respect to `x`.
928 btdtrib : Inverse with respect to `b`.
930 Notes
931 -----
932 Wrapper for the CDFLIB [1]_ Fortran routine `cdfbet`.
934 The cumulative distribution function `p` is computed using a routine by
935 DiDinato and Morris [2]_. Computation of `a` involves a search for a value
936 that produces the desired value of `p`. The search relies on the
937 monotonicity of `p` with `a`.
939 References
940 ----------
941 .. [1] Barry Brown, James Lovato, and Kathy Russell,
942 CDFLIB: Library of Fortran Routines for Cumulative Distribution
943 Functions, Inverses, and Other Parameters.
944 .. [2] DiDinato, A. R. and Morris, A. H.,
945 Algorithm 708: Significant Digit Computation of the Incomplete Beta
946 Function Ratios. ACM Trans. Math. Softw. 18 (1993), 360-373.
948 """)
950add_newdoc("btdtrib",
951 r"""
952 btdtria(a, p, x, out=None)
954 Inverse of `btdtr` with respect to `b`.
956 This is the inverse of the beta cumulative distribution function, `btdtr`,
957 considered as a function of `b`, returning the value of `b` for which
958 `btdtr(a, b, x) = p`, or
960 .. math::
961 p = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
963 Parameters
964 ----------
965 a : array_like
966 Shape parameter (`a` > 0).
967 p : array_like
968 Cumulative probability, in [0, 1].
969 x : array_like
970 The quantile, in [0, 1].
971 out : ndarray, optional
972 Optional output array for the function values
974 Returns
975 -------
976 b : scalar or ndarray
977 The value of the shape parameter `b` such that `btdtr(a, b, x) = p`.
979 See Also
980 --------
981 btdtr : Cumulative distribution function of the beta distribution.
982 btdtri : Inverse with respect to `x`.
983 btdtria : Inverse with respect to `a`.
985 Notes
986 -----
987 Wrapper for the CDFLIB [1]_ Fortran routine `cdfbet`.
989 The cumulative distribution function `p` is computed using a routine by
990 DiDinato and Morris [2]_. Computation of `b` involves a search for a value
991 that produces the desired value of `p`. The search relies on the
992 monotonicity of `p` with `b`.
994 References
995 ----------
996 .. [1] Barry Brown, James Lovato, and Kathy Russell,
997 CDFLIB: Library of Fortran Routines for Cumulative Distribution
998 Functions, Inverses, and Other Parameters.
999 .. [2] DiDinato, A. R. and Morris, A. H.,
1000 Algorithm 708: Significant Digit Computation of the Incomplete Beta
1001 Function Ratios. ACM Trans. Math. Softw. 18 (1993), 360-373.
1004 """)
1006add_newdoc("bei",
1007 r"""
1008 bei(x, out=None)
1010 Kelvin function bei.
1012 Defined as
1014 .. math::
1016 \mathrm{bei}(x) = \Im[J_0(x e^{3 \pi i / 4})]
1018 where :math:`J_0` is the Bessel function of the first kind of
1019 order zero (see `jv`). See [dlmf]_ for more details.
1021 Parameters
1022 ----------
1023 x : array_like
1024 Real argument.
1025 out : ndarray, optional
1026 Optional output array for the function results.
1028 Returns
1029 -------
1030 scalar or ndarray
1031 Values of the Kelvin function.
1033 See Also
1034 --------
1035 ber : the corresponding real part
1036 beip : the derivative of bei
1037 jv : Bessel function of the first kind
1039 References
1040 ----------
1041 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1042 https://dlmf.nist.gov/10.61
1044 Examples
1045 --------
1046 It can be expressed using Bessel functions.
1048 >>> import numpy as np
1049 >>> import scipy.special as sc
1050 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
1051 >>> sc.jv(0, x * np.exp(3 * np.pi * 1j / 4)).imag
1052 array([0.24956604, 0.97229163, 1.93758679, 2.29269032])
1053 >>> sc.bei(x)
1054 array([0.24956604, 0.97229163, 1.93758679, 2.29269032])
1056 """)
1058add_newdoc("beip",
1059 r"""
1060 beip(x, out=None)
1062 Derivative of the Kelvin function bei.
1064 Parameters
1065 ----------
1066 x : array_like
1067 Real argument.
1068 out : ndarray, optional
1069 Optional output array for the function results.
1071 Returns
1072 -------
1073 scalar or ndarray
1074 The values of the derivative of bei.
1076 See Also
1077 --------
1078 bei
1080 References
1081 ----------
1082 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1083 https://dlmf.nist.gov/10#PT5
1085 """)
1087add_newdoc("ber",
1088 r"""
1089 ber(x, out=None)
1091 Kelvin function ber.
1093 Defined as
1095 .. math::
1097 \mathrm{ber}(x) = \Re[J_0(x e^{3 \pi i / 4})]
1099 where :math:`J_0` is the Bessel function of the first kind of
1100 order zero (see `jv`). See [dlmf]_ for more details.
1102 Parameters
1103 ----------
1104 x : array_like
1105 Real argument.
1106 out : ndarray, optional
1107 Optional output array for the function results.
1109 Returns
1110 -------
1111 scalar or ndarray
1112 Values of the Kelvin function.
1114 See Also
1115 --------
1116 bei : the corresponding real part
1117 berp : the derivative of bei
1118 jv : Bessel function of the first kind
1120 References
1121 ----------
1122 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1123 https://dlmf.nist.gov/10.61
1125 Examples
1126 --------
1127 It can be expressed using Bessel functions.
1129 >>> import numpy as np
1130 >>> import scipy.special as sc
1131 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
1132 >>> sc.jv(0, x * np.exp(3 * np.pi * 1j / 4)).real
1133 array([ 0.98438178, 0.75173418, -0.22138025, -2.56341656])
1134 >>> sc.ber(x)
1135 array([ 0.98438178, 0.75173418, -0.22138025, -2.56341656])
1137 """)
1139add_newdoc("berp",
1140 r"""
1141 berp(x, out=None)
1143 Derivative of the Kelvin function ber.
1145 Parameters
1146 ----------
1147 x : array_like
1148 Real argument.
1149 out : ndarray, optional
1150 Optional output array for the function results.
1152 Returns
1153 -------
1154 scalar or ndarray
1155 The values of the derivative of ber.
1157 See Also
1158 --------
1159 ber
1161 References
1162 ----------
1163 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1164 https://dlmf.nist.gov/10#PT5
1166 """)
1168add_newdoc("besselpoly",
1169 r"""
1170 besselpoly(a, lmb, nu, out=None)
1172 Weighted integral of the Bessel function of the first kind.
1174 Computes
1176 .. math::
1178 \int_0^1 x^\lambda J_\nu(2 a x) \, dx
1180 where :math:`J_\nu` is a Bessel function and :math:`\lambda=lmb`,
1181 :math:`\nu=nu`.
1183 Parameters
1184 ----------
1185 a : array_like
1186 Scale factor inside the Bessel function.
1187 lmb : array_like
1188 Power of `x`
1189 nu : array_like
1190 Order of the Bessel function.
1191 out : ndarray, optional
1192 Optional output array for the function results.
1194 Returns
1195 -------
1196 scalar or ndarray
1197 Value of the integral.
1199 References
1200 ----------
1201 .. [1] Cephes Mathematical Functions Library,
1202 http://www.netlib.org/cephes/
1204 Examples
1205 --------
1206 Evaluate the function for one parameter set.
1208 >>> from scipy.special import besselpoly
1209 >>> besselpoly(1, 1, 1)
1210 0.24449718372863877
1212 Evaluate the function for different scale factors.
1214 >>> import numpy as np
1215 >>> factors = np.array([0., 3., 6.])
1216 >>> besselpoly(factors, 1, 1)
1217 array([ 0. , -0.00549029, 0.00140174])
1219 Plot the function for varying powers, orders and scales.
1221 >>> import matplotlib.pyplot as plt
1222 >>> fig, ax = plt.subplots()
1223 >>> powers = np.linspace(0, 10, 100)
1224 >>> orders = [1, 2, 3]
1225 >>> scales = [1, 2]
1226 >>> all_combinations = [(order, scale) for order in orders
1227 ... for scale in scales]
1228 >>> for order, scale in all_combinations:
1229 ... ax.plot(powers, besselpoly(scale, powers, order),
1230 ... label=rf"$\nu={order}, a={scale}$")
1231 >>> ax.legend()
1232 >>> ax.set_xlabel(r"$\lambda$")
1233 >>> ax.set_ylabel(r"$\int_0^1 x^{\lambda} J_{\nu}(2ax)\,dx$")
1234 >>> plt.show()
1235 """)
1237add_newdoc("beta",
1238 r"""
1239 beta(a, b, out=None)
1241 Beta function.
1243 This function is defined in [1]_ as
1245 .. math::
1247 B(a, b) = \int_0^1 t^{a-1}(1-t)^{b-1}dt
1248 = \frac{\Gamma(a)\Gamma(b)}{\Gamma(a+b)},
1250 where :math:`\Gamma` is the gamma function.
1252 Parameters
1253 ----------
1254 a, b : array_like
1255 Real-valued arguments
1256 out : ndarray, optional
1257 Optional output array for the function result
1259 Returns
1260 -------
1261 scalar or ndarray
1262 Value of the beta function
1264 See Also
1265 --------
1266 gamma : the gamma function
1267 betainc : the regularized incomplete beta function
1268 betaln : the natural logarithm of the absolute
1269 value of the beta function
1271 References
1272 ----------
1273 .. [1] NIST Digital Library of Mathematical Functions,
1274 Eq. 5.12.1. https://dlmf.nist.gov/5.12
1276 Examples
1277 --------
1278 >>> import scipy.special as sc
1280 The beta function relates to the gamma function by the
1281 definition given above:
1283 >>> sc.beta(2, 3)
1284 0.08333333333333333
1285 >>> sc.gamma(2)*sc.gamma(3)/sc.gamma(2 + 3)
1286 0.08333333333333333
1288 As this relationship demonstrates, the beta function
1289 is symmetric:
1291 >>> sc.beta(1.7, 2.4)
1292 0.16567527689031739
1293 >>> sc.beta(2.4, 1.7)
1294 0.16567527689031739
1296 This function satisfies :math:`B(1, b) = 1/b`:
1298 >>> sc.beta(1, 4)
1299 0.25
1301 """)
1303add_newdoc("betainc",
1304 r"""
1305 betainc(a, b, x, out=None)
1307 Regularized incomplete beta function.
1309 Computes the regularized incomplete beta function, defined as [1]_:
1311 .. math::
1313 I_x(a, b) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)} \int_0^x
1314 t^{a-1}(1-t)^{b-1}dt,
1316 for :math:`0 \leq x \leq 1`.
1318 Parameters
1319 ----------
1320 a, b : array_like
1321 Positive, real-valued parameters
1322 x : array_like
1323 Real-valued such that :math:`0 \leq x \leq 1`,
1324 the upper limit of integration
1325 out : ndarray, optional
1326 Optional output array for the function values
1328 Returns
1329 -------
1330 scalar or ndarray
1331 Value of the regularized incomplete beta function
1333 See Also
1334 --------
1335 beta : beta function
1336 betaincinv : inverse of the regularized incomplete beta function
1338 Notes
1339 -----
1340 The term *regularized* in the name of this function refers to the
1341 scaling of the function by the gamma function terms shown in the
1342 formula. When not qualified as *regularized*, the name *incomplete
1343 beta function* often refers to just the integral expression,
1344 without the gamma terms. One can use the function `beta` from
1345 `scipy.special` to get this "nonregularized" incomplete beta
1346 function by multiplying the result of ``betainc(a, b, x)`` by
1347 ``beta(a, b)``.
1349 References
1350 ----------
1351 .. [1] NIST Digital Library of Mathematical Functions
1352 https://dlmf.nist.gov/8.17
1354 Examples
1355 --------
1357 Let :math:`B(a, b)` be the `beta` function.
1359 >>> import scipy.special as sc
1361 The coefficient in terms of `gamma` is equal to
1362 :math:`1/B(a, b)`. Also, when :math:`x=1`
1363 the integral is equal to :math:`B(a, b)`.
1364 Therefore, :math:`I_{x=1}(a, b) = 1` for any :math:`a, b`.
1366 >>> sc.betainc(0.2, 3.5, 1.0)
1367 1.0
1369 It satisfies
1370 :math:`I_x(a, b) = x^a F(a, 1-b, a+1, x)/ (aB(a, b))`,
1371 where :math:`F` is the hypergeometric function `hyp2f1`:
1373 >>> a, b, x = 1.4, 3.1, 0.5
1374 >>> x**a * sc.hyp2f1(a, 1 - b, a + 1, x)/(a * sc.beta(a, b))
1375 0.8148904036225295
1376 >>> sc.betainc(a, b, x)
1377 0.8148904036225296
1379 This functions satisfies the relationship
1380 :math:`I_x(a, b) = 1 - I_{1-x}(b, a)`:
1382 >>> sc.betainc(2.2, 3.1, 0.4)
1383 0.49339638807619446
1384 >>> 1 - sc.betainc(3.1, 2.2, 1 - 0.4)
1385 0.49339638807619446
1387 """)
1389add_newdoc("betaincinv",
1390 r"""
1391 betaincinv(a, b, y, out=None)
1393 Inverse of the regularized incomplete beta function.
1395 Computes :math:`x` such that:
1397 .. math::
1399 y = I_x(a, b) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)}
1400 \int_0^x t^{a-1}(1-t)^{b-1}dt,
1402 where :math:`I_x` is the normalized incomplete beta
1403 function `betainc` and
1404 :math:`\Gamma` is the `gamma` function [1]_.
1406 Parameters
1407 ----------
1408 a, b : array_like
1409 Positive, real-valued parameters
1410 y : array_like
1411 Real-valued input
1412 out : ndarray, optional
1413 Optional output array for function values
1415 Returns
1416 -------
1417 scalar or ndarray
1418 Value of the inverse of the regularized incomplete beta function
1420 See Also
1421 --------
1422 betainc : regularized incomplete beta function
1423 gamma : gamma function
1425 References
1426 ----------
1427 .. [1] NIST Digital Library of Mathematical Functions
1428 https://dlmf.nist.gov/8.17
1430 Examples
1431 --------
1432 >>> import scipy.special as sc
1434 This function is the inverse of `betainc` for fixed
1435 values of :math:`a` and :math:`b`.
1437 >>> a, b = 1.2, 3.1
1438 >>> y = sc.betainc(a, b, 0.2)
1439 >>> sc.betaincinv(a, b, y)
1440 0.2
1441 >>>
1442 >>> a, b = 7.5, 0.4
1443 >>> x = sc.betaincinv(a, b, 0.5)
1444 >>> sc.betainc(a, b, x)
1445 0.5
1447 """)
1449add_newdoc("betaln",
1450 """
1451 betaln(a, b, out=None)
1453 Natural logarithm of absolute value of beta function.
1455 Computes ``ln(abs(beta(a, b)))``.
1457 Parameters
1458 ----------
1459 a, b : array_like
1460 Positive, real-valued parameters
1461 out : ndarray, optional
1462 Optional output array for function values
1464 Returns
1465 -------
1466 scalar or ndarray
1467 Value of the betaln function
1469 See Also
1470 --------
1471 gamma : the gamma function
1472 betainc : the regularized incomplete beta function
1473 beta : the beta function
1475 Examples
1476 --------
1477 >>> import numpy as np
1478 >>> from scipy.special import betaln, beta
1480 Verify that, for moderate values of ``a`` and ``b``, ``betaln(a, b)``
1481 is the same as ``log(beta(a, b))``:
1483 >>> betaln(3, 4)
1484 -4.0943445622221
1486 >>> np.log(beta(3, 4))
1487 -4.0943445622221
1489 In the following ``beta(a, b)`` underflows to 0, so we can't compute
1490 the logarithm of the actual value.
1492 >>> a = 400
1493 >>> b = 900
1494 >>> beta(a, b)
1495 0.0
1497 We can compute the logarithm of ``beta(a, b)`` by using `betaln`:
1499 >>> betaln(a, b)
1500 -804.3069951764146
1502 """)
1504add_newdoc("boxcox",
1505 """
1506 boxcox(x, lmbda, out=None)
1508 Compute the Box-Cox transformation.
1510 The Box-Cox transformation is::
1512 y = (x**lmbda - 1) / lmbda if lmbda != 0
1513 log(x) if lmbda == 0
1515 Returns `nan` if ``x < 0``.
1516 Returns `-inf` if ``x == 0`` and ``lmbda < 0``.
1518 Parameters
1519 ----------
1520 x : array_like
1521 Data to be transformed.
1522 lmbda : array_like
1523 Power parameter of the Box-Cox transform.
1524 out : ndarray, optional
1525 Optional output array for the function values
1527 Returns
1528 -------
1529 y : scalar or ndarray
1530 Transformed data.
1532 Notes
1533 -----
1535 .. versionadded:: 0.14.0
1537 Examples
1538 --------
1539 >>> from scipy.special import boxcox
1540 >>> boxcox([1, 4, 10], 2.5)
1541 array([ 0. , 12.4 , 126.09110641])
1542 >>> boxcox(2, [0, 1, 2])
1543 array([ 0.69314718, 1. , 1.5 ])
1544 """)
1546add_newdoc("boxcox1p",
1547 """
1548 boxcox1p(x, lmbda, out=None)
1550 Compute the Box-Cox transformation of 1 + `x`.
1552 The Box-Cox transformation computed by `boxcox1p` is::
1554 y = ((1+x)**lmbda - 1) / lmbda if lmbda != 0
1555 log(1+x) if lmbda == 0
1557 Returns `nan` if ``x < -1``.
1558 Returns `-inf` if ``x == -1`` and ``lmbda < 0``.
1560 Parameters
1561 ----------
1562 x : array_like
1563 Data to be transformed.
1564 lmbda : array_like
1565 Power parameter of the Box-Cox transform.
1566 out : ndarray, optional
1567 Optional output array for the function values
1569 Returns
1570 -------
1571 y : scalar or ndarray
1572 Transformed data.
1574 Notes
1575 -----
1577 .. versionadded:: 0.14.0
1579 Examples
1580 --------
1581 >>> from scipy.special import boxcox1p
1582 >>> boxcox1p(1e-4, [0, 0.5, 1])
1583 array([ 9.99950003e-05, 9.99975001e-05, 1.00000000e-04])
1584 >>> boxcox1p([0.01, 0.1], 0.25)
1585 array([ 0.00996272, 0.09645476])
1586 """)
1588add_newdoc("inv_boxcox",
1589 """
1590 inv_boxcox(y, lmbda, out=None)
1592 Compute the inverse of the Box-Cox transformation.
1594 Find ``x`` such that::
1596 y = (x**lmbda - 1) / lmbda if lmbda != 0
1597 log(x) if lmbda == 0
1599 Parameters
1600 ----------
1601 y : array_like
1602 Data to be transformed.
1603 lmbda : array_like
1604 Power parameter of the Box-Cox transform.
1605 out : ndarray, optional
1606 Optional output array for the function values
1608 Returns
1609 -------
1610 x : scalar or ndarray
1611 Transformed data.
1613 Notes
1614 -----
1616 .. versionadded:: 0.16.0
1618 Examples
1619 --------
1620 >>> from scipy.special import boxcox, inv_boxcox
1621 >>> y = boxcox([1, 4, 10], 2.5)
1622 >>> inv_boxcox(y, 2.5)
1623 array([1., 4., 10.])
1624 """)
1626add_newdoc("inv_boxcox1p",
1627 """
1628 inv_boxcox1p(y, lmbda, out=None)
1630 Compute the inverse of the Box-Cox transformation.
1632 Find ``x`` such that::
1634 y = ((1+x)**lmbda - 1) / lmbda if lmbda != 0
1635 log(1+x) if lmbda == 0
1637 Parameters
1638 ----------
1639 y : array_like
1640 Data to be transformed.
1641 lmbda : array_like
1642 Power parameter of the Box-Cox transform.
1643 out : ndarray, optional
1644 Optional output array for the function values
1646 Returns
1647 -------
1648 x : scalar or ndarray
1649 Transformed data.
1651 Notes
1652 -----
1654 .. versionadded:: 0.16.0
1656 Examples
1657 --------
1658 >>> from scipy.special import boxcox1p, inv_boxcox1p
1659 >>> y = boxcox1p([1, 4, 10], 2.5)
1660 >>> inv_boxcox1p(y, 2.5)
1661 array([1., 4., 10.])
1662 """)
1664add_newdoc("btdtr",
1665 r"""
1666 btdtr(a, b, x, out=None)
1668 Cumulative distribution function of the beta distribution.
1670 Returns the integral from zero to `x` of the beta probability density
1671 function,
1673 .. math::
1674 I = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
1676 where :math:`\Gamma` is the gamma function.
1678 Parameters
1679 ----------
1680 a : array_like
1681 Shape parameter (a > 0).
1682 b : array_like
1683 Shape parameter (b > 0).
1684 x : array_like
1685 Upper limit of integration, in [0, 1].
1686 out : ndarray, optional
1687 Optional output array for the function values
1689 Returns
1690 -------
1691 I : scalar or ndarray
1692 Cumulative distribution function of the beta distribution with
1693 parameters `a` and `b` at `x`.
1695 See Also
1696 --------
1697 betainc
1699 Notes
1700 -----
1701 This function is identical to the incomplete beta integral function
1702 `betainc`.
1704 Wrapper for the Cephes [1]_ routine `btdtr`.
1706 References
1707 ----------
1708 .. [1] Cephes Mathematical Functions Library,
1709 http://www.netlib.org/cephes/
1711 """)
1713add_newdoc("btdtri",
1714 r"""
1715 btdtri(a, b, p, out=None)
1717 The `p`-th quantile of the beta distribution.
1719 This function is the inverse of the beta cumulative distribution function,
1720 `btdtr`, returning the value of `x` for which `btdtr(a, b, x) = p`, or
1722 .. math::
1723 p = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
1725 Parameters
1726 ----------
1727 a : array_like
1728 Shape parameter (`a` > 0).
1729 b : array_like
1730 Shape parameter (`b` > 0).
1731 p : array_like
1732 Cumulative probability, in [0, 1].
1733 out : ndarray, optional
1734 Optional output array for the function values
1736 Returns
1737 -------
1738 x : scalar or ndarray
1739 The quantile corresponding to `p`.
1741 See Also
1742 --------
1743 betaincinv
1744 btdtr
1746 Notes
1747 -----
1748 The value of `x` is found by interval halving or Newton iterations.
1750 Wrapper for the Cephes [1]_ routine `incbi`, which solves the equivalent
1751 problem of finding the inverse of the incomplete beta integral.
1753 References
1754 ----------
1755 .. [1] Cephes Mathematical Functions Library,
1756 http://www.netlib.org/cephes/
1758 """)
1760add_newdoc("cbrt",
1761 """
1762 cbrt(x, out=None)
1764 Element-wise cube root of `x`.
1766 Parameters
1767 ----------
1768 x : array_like
1769 `x` must contain real numbers.
1770 out : ndarray, optional
1771 Optional output array for the function values
1773 Returns
1774 -------
1775 scalar or ndarray
1776 The cube root of each value in `x`.
1778 Examples
1779 --------
1780 >>> from scipy.special import cbrt
1782 >>> cbrt(8)
1783 2.0
1784 >>> cbrt([-8, -3, 0.125, 1.331])
1785 array([-2. , -1.44224957, 0.5 , 1.1 ])
1787 """)
1789add_newdoc("chdtr",
1790 r"""
1791 chdtr(v, x, out=None)
1793 Chi square cumulative distribution function.
1795 Returns the area under the left tail (from 0 to `x`) of the Chi
1796 square probability density function with `v` degrees of freedom:
1798 .. math::
1800 \frac{1}{2^{v/2} \Gamma(v/2)} \int_0^x t^{v/2 - 1} e^{-t/2} dt
1802 Here :math:`\Gamma` is the Gamma function; see `gamma`. This
1803 integral can be expressed in terms of the regularized lower
1804 incomplete gamma function `gammainc` as
1805 ``gammainc(v / 2, x / 2)``. [1]_
1807 Parameters
1808 ----------
1809 v : array_like
1810 Degrees of freedom.
1811 x : array_like
1812 Upper bound of the integral.
1813 out : ndarray, optional
1814 Optional output array for the function results.
1816 Returns
1817 -------
1818 scalar or ndarray
1819 Values of the cumulative distribution function.
1821 See Also
1822 --------
1823 chdtrc, chdtri, chdtriv, gammainc
1825 References
1826 ----------
1827 .. [1] Chi-Square distribution,
1828 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1830 Examples
1831 --------
1832 >>> import numpy as np
1833 >>> import scipy.special as sc
1835 It can be expressed in terms of the regularized lower incomplete
1836 gamma function.
1838 >>> v = 1
1839 >>> x = np.arange(4)
1840 >>> sc.chdtr(v, x)
1841 array([0. , 0.68268949, 0.84270079, 0.91673548])
1842 >>> sc.gammainc(v / 2, x / 2)
1843 array([0. , 0.68268949, 0.84270079, 0.91673548])
1845 """)
1847add_newdoc("chdtrc",
1848 r"""
1849 chdtrc(v, x, out=None)
1851 Chi square survival function.
1853 Returns the area under the right hand tail (from `x` to infinity)
1854 of the Chi square probability density function with `v` degrees of
1855 freedom:
1857 .. math::
1859 \frac{1}{2^{v/2} \Gamma(v/2)} \int_x^\infty t^{v/2 - 1} e^{-t/2} dt
1861 Here :math:`\Gamma` is the Gamma function; see `gamma`. This
1862 integral can be expressed in terms of the regularized upper
1863 incomplete gamma function `gammaincc` as
1864 ``gammaincc(v / 2, x / 2)``. [1]_
1866 Parameters
1867 ----------
1868 v : array_like
1869 Degrees of freedom.
1870 x : array_like
1871 Lower bound of the integral.
1872 out : ndarray, optional
1873 Optional output array for the function results.
1875 Returns
1876 -------
1877 scalar or ndarray
1878 Values of the survival function.
1880 See Also
1881 --------
1882 chdtr, chdtri, chdtriv, gammaincc
1884 References
1885 ----------
1886 .. [1] Chi-Square distribution,
1887 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1889 Examples
1890 --------
1891 >>> import numpy as np
1892 >>> import scipy.special as sc
1894 It can be expressed in terms of the regularized upper incomplete
1895 gamma function.
1897 >>> v = 1
1898 >>> x = np.arange(4)
1899 >>> sc.chdtrc(v, x)
1900 array([1. , 0.31731051, 0.15729921, 0.08326452])
1901 >>> sc.gammaincc(v / 2, x / 2)
1902 array([1. , 0.31731051, 0.15729921, 0.08326452])
1904 """)
1906add_newdoc("chdtri",
1907 """
1908 chdtri(v, p, out=None)
1910 Inverse to `chdtrc` with respect to `x`.
1912 Returns `x` such that ``chdtrc(v, x) == p``.
1914 Parameters
1915 ----------
1916 v : array_like
1917 Degrees of freedom.
1918 p : array_like
1919 Probability.
1920 out : ndarray, optional
1921 Optional output array for the function results.
1923 Returns
1924 -------
1925 x : scalar or ndarray
1926 Value so that the probability a Chi square random variable
1927 with `v` degrees of freedom is greater than `x` equals `p`.
1929 See Also
1930 --------
1931 chdtrc, chdtr, chdtriv
1933 References
1934 ----------
1935 .. [1] Chi-Square distribution,
1936 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1938 Examples
1939 --------
1940 >>> import scipy.special as sc
1942 It inverts `chdtrc`.
1944 >>> v, p = 1, 0.3
1945 >>> sc.chdtrc(v, sc.chdtri(v, p))
1946 0.3
1947 >>> x = 1
1948 >>> sc.chdtri(v, sc.chdtrc(v, x))
1949 1.0
1951 """)
1953add_newdoc("chdtriv",
1954 """
1955 chdtriv(p, x, out=None)
1957 Inverse to `chdtr` with respect to `v`.
1959 Returns `v` such that ``chdtr(v, x) == p``.
1961 Parameters
1962 ----------
1963 p : array_like
1964 Probability that the Chi square random variable is less than
1965 or equal to `x`.
1966 x : array_like
1967 Nonnegative input.
1968 out : ndarray, optional
1969 Optional output array for the function results.
1971 Returns
1972 -------
1973 scalar or ndarray
1974 Degrees of freedom.
1976 See Also
1977 --------
1978 chdtr, chdtrc, chdtri
1980 References
1981 ----------
1982 .. [1] Chi-Square distribution,
1983 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1985 Examples
1986 --------
1987 >>> import scipy.special as sc
1989 It inverts `chdtr`.
1991 >>> p, x = 0.5, 1
1992 >>> sc.chdtr(sc.chdtriv(p, x), x)
1993 0.5000000000202172
1994 >>> v = 1
1995 >>> sc.chdtriv(sc.chdtr(v, x), v)
1996 1.0000000000000013
1998 """)
2000add_newdoc("chndtr",
2001 r"""
2002 chndtr(x, df, nc, out=None)
2004 Non-central chi square cumulative distribution function
2006 The cumulative distribution function is given by:
2008 .. math::
2010 P(\chi^{\prime 2} \vert \nu, \lambda) =\sum_{j=0}^{\infty}
2011 e^{-\lambda /2}
2012 \frac{(\lambda /2)^j}{j!} P(\chi^{\prime 2} \vert \nu + 2j),
2014 where :math:`\nu > 0` is the degrees of freedom (``df``) and
2015 :math:`\lambda \geq 0` is the non-centrality parameter (``nc``).
2017 Parameters
2018 ----------
2019 x : array_like
2020 Upper bound of the integral; must satisfy ``x >= 0``
2021 df : array_like
2022 Degrees of freedom; must satisfy ``df > 0``
2023 nc : array_like
2024 Non-centrality parameter; must satisfy ``nc >= 0``
2025 out : ndarray, optional
2026 Optional output array for the function results
2028 Returns
2029 -------
2030 x : scalar or ndarray
2031 Value of the non-central chi square cumulative distribution function.
2033 See Also
2034 --------
2035 chndtrix, chndtridf, chndtrinc
2037 """)
2039add_newdoc("chndtrix",
2040 """
2041 chndtrix(p, df, nc, out=None)
2043 Inverse to `chndtr` vs `x`
2045 Calculated using a search to find a value for `x` that produces the
2046 desired value of `p`.
2048 Parameters
2049 ----------
2050 p : array_like
2051 Probability; must satisfy ``0 <= p < 1``
2052 df : array_like
2053 Degrees of freedom; must satisfy ``df > 0``
2054 nc : array_like
2055 Non-centrality parameter; must satisfy ``nc >= 0``
2056 out : ndarray, optional
2057 Optional output array for the function results
2059 Returns
2060 -------
2061 x : scalar or ndarray
2062 Value so that the probability a non-central Chi square random variable
2063 with `df` degrees of freedom and non-centrality, `nc`, is greater than
2064 `x` equals `p`.
2066 See Also
2067 --------
2068 chndtr, chndtridf, chndtrinc
2070 """)
2072add_newdoc("chndtridf",
2073 """
2074 chndtridf(x, p, nc, out=None)
2076 Inverse to `chndtr` vs `df`
2078 Calculated using a search to find a value for `df` that produces the
2079 desired value of `p`.
2081 Parameters
2082 ----------
2083 x : array_like
2084 Upper bound of the integral; must satisfy ``x >= 0``
2085 p : array_like
2086 Probability; must satisfy ``0 <= p < 1``
2087 nc : array_like
2088 Non-centrality parameter; must satisfy ``nc >= 0``
2089 out : ndarray, optional
2090 Optional output array for the function results
2092 Returns
2093 -------
2094 df : scalar or ndarray
2095 Degrees of freedom
2097 See Also
2098 --------
2099 chndtr, chndtrix, chndtrinc
2101 """)
2103add_newdoc("chndtrinc",
2104 """
2105 chndtrinc(x, df, p, out=None)
2107 Inverse to `chndtr` vs `nc`
2109 Calculated using a search to find a value for `df` that produces the
2110 desired value of `p`.
2112 Parameters
2113 ----------
2114 x : array_like
2115 Upper bound of the integral; must satisfy ``x >= 0``
2116 df : array_like
2117 Degrees of freedom; must satisfy ``df > 0``
2118 p : array_like
2119 Probability; must satisfy ``0 <= p < 1``
2120 out : ndarray, optional
2121 Optional output array for the function results
2123 Returns
2124 -------
2125 nc : scalar or ndarray
2126 Non-centrality
2128 See Also
2129 --------
2130 chndtr, chndtrix, chndtrinc
2132 """)
2134add_newdoc("cosdg",
2135 """
2136 cosdg(x, out=None)
2138 Cosine of the angle `x` given in degrees.
2140 Parameters
2141 ----------
2142 x : array_like
2143 Angle, given in degrees.
2144 out : ndarray, optional
2145 Optional output array for the function results.
2147 Returns
2148 -------
2149 scalar or ndarray
2150 Cosine of the input.
2152 See Also
2153 --------
2154 sindg, tandg, cotdg
2156 Examples
2157 --------
2158 >>> import numpy as np
2159 >>> import scipy.special as sc
2161 It is more accurate than using cosine directly.
2163 >>> x = 90 + 180 * np.arange(3)
2164 >>> sc.cosdg(x)
2165 array([-0., 0., -0.])
2166 >>> np.cos(x * np.pi / 180)
2167 array([ 6.1232340e-17, -1.8369702e-16, 3.0616170e-16])
2169 """)
2171add_newdoc("cosm1",
2172 """
2173 cosm1(x, out=None)
2175 cos(x) - 1 for use when `x` is near zero.
2177 Parameters
2178 ----------
2179 x : array_like
2180 Real valued argument.
2181 out : ndarray, optional
2182 Optional output array for the function results.
2184 Returns
2185 -------
2186 scalar or ndarray
2187 Values of ``cos(x) - 1``.
2189 See Also
2190 --------
2191 expm1, log1p
2193 Examples
2194 --------
2195 >>> import numpy as np
2196 >>> import scipy.special as sc
2198 It is more accurate than computing ``cos(x) - 1`` directly for
2199 ``x`` around 0.
2201 >>> x = 1e-30
2202 >>> np.cos(x) - 1
2203 0.0
2204 >>> sc.cosm1(x)
2205 -5.0000000000000005e-61
2207 """)
2209add_newdoc("cotdg",
2210 """
2211 cotdg(x, out=None)
2213 Cotangent of the angle `x` given in degrees.
2215 Parameters
2216 ----------
2217 x : array_like
2218 Angle, given in degrees.
2219 out : ndarray, optional
2220 Optional output array for the function results.
2222 Returns
2223 -------
2224 scalar or ndarray
2225 Cotangent at the input.
2227 See Also
2228 --------
2229 sindg, cosdg, tandg
2231 Examples
2232 --------
2233 >>> import numpy as np
2234 >>> import scipy.special as sc
2236 It is more accurate than using cotangent directly.
2238 >>> x = 90 + 180 * np.arange(3)
2239 >>> sc.cotdg(x)
2240 array([0., 0., 0.])
2241 >>> 1 / np.tan(x * np.pi / 180)
2242 array([6.1232340e-17, 1.8369702e-16, 3.0616170e-16])
2244 """)
2246add_newdoc("dawsn",
2247 """
2248 dawsn(x, out=None)
2250 Dawson's integral.
2252 Computes::
2254 exp(-x**2) * integral(exp(t**2), t=0..x).
2256 Parameters
2257 ----------
2258 x : array_like
2259 Function parameter.
2260 out : ndarray, optional
2261 Optional output array for the function values
2263 Returns
2264 -------
2265 y : scalar or ndarray
2266 Value of the integral.
2268 See Also
2269 --------
2270 wofz, erf, erfc, erfcx, erfi
2272 References
2273 ----------
2274 .. [1] Steven G. Johnson, Faddeeva W function implementation.
2275 http://ab-initio.mit.edu/Faddeeva
2277 Examples
2278 --------
2279 >>> import numpy as np
2280 >>> from scipy import special
2281 >>> import matplotlib.pyplot as plt
2282 >>> x = np.linspace(-15, 15, num=1000)
2283 >>> plt.plot(x, special.dawsn(x))
2284 >>> plt.xlabel('$x$')
2285 >>> plt.ylabel('$dawsn(x)$')
2286 >>> plt.show()
2288 """)
2290add_newdoc("ellipe",
2291 r"""
2292 ellipe(m, out=None)
2294 Complete elliptic integral of the second kind
2296 This function is defined as
2298 .. math:: E(m) = \int_0^{\pi/2} [1 - m \sin(t)^2]^{1/2} dt
2300 Parameters
2301 ----------
2302 m : array_like
2303 Defines the parameter of the elliptic integral.
2304 out : ndarray, optional
2305 Optional output array for the function values
2307 Returns
2308 -------
2309 E : scalar or ndarray
2310 Value of the elliptic integral.
2312 Notes
2313 -----
2314 Wrapper for the Cephes [1]_ routine `ellpe`.
2316 For `m > 0` the computation uses the approximation,
2318 .. math:: E(m) \approx P(1-m) - (1-m) \log(1-m) Q(1-m),
2320 where :math:`P` and :math:`Q` are tenth-order polynomials. For
2321 `m < 0`, the relation
2323 .. math:: E(m) = E(m/(m - 1)) \sqrt(1-m)
2325 is used.
2327 The parameterization in terms of :math:`m` follows that of section
2328 17.2 in [2]_. Other parameterizations in terms of the
2329 complementary parameter :math:`1 - m`, modular angle
2330 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2331 used, so be careful that you choose the correct parameter.
2333 The Legendre E integral is related to Carlson's symmetric R_D or R_G
2334 functions in multiple ways [3]_. For example,
2336 .. math:: E(m) = 2 R_G(0, 1-k^2, 1) .
2338 See Also
2339 --------
2340 ellipkm1 : Complete elliptic integral of the first kind, near `m` = 1
2341 ellipk : Complete elliptic integral of the first kind
2342 ellipkinc : Incomplete elliptic integral of the first kind
2343 ellipeinc : Incomplete elliptic integral of the second kind
2344 elliprd : Symmetric elliptic integral of the second kind.
2345 elliprg : Completely-symmetric elliptic integral of the second kind.
2347 References
2348 ----------
2349 .. [1] Cephes Mathematical Functions Library,
2350 http://www.netlib.org/cephes/
2351 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
2352 Handbook of Mathematical Functions with Formulas,
2353 Graphs, and Mathematical Tables. New York: Dover, 1972.
2354 .. [3] NIST Digital Library of Mathematical
2355 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2356 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2358 Examples
2359 --------
2360 This function is used in finding the circumference of an
2361 ellipse with semi-major axis `a` and semi-minor axis `b`.
2363 >>> import numpy as np
2364 >>> from scipy import special
2366 >>> a = 3.5
2367 >>> b = 2.1
2368 >>> e_sq = 1.0 - b**2/a**2 # eccentricity squared
2370 Then the circumference is found using the following:
2372 >>> C = 4*a*special.ellipe(e_sq) # circumference formula
2373 >>> C
2374 17.868899204378693
2376 When `a` and `b` are the same (meaning eccentricity is 0),
2377 this reduces to the circumference of a circle.
2379 >>> 4*a*special.ellipe(0.0) # formula for ellipse with a = b
2380 21.991148575128552
2381 >>> 2*np.pi*a # formula for circle of radius a
2382 21.991148575128552
2384 """)
2386add_newdoc("ellipeinc",
2387 r"""
2388 ellipeinc(phi, m, out=None)
2390 Incomplete elliptic integral of the second kind
2392 This function is defined as
2394 .. math:: E(\phi, m) = \int_0^{\phi} [1 - m \sin(t)^2]^{1/2} dt
2396 Parameters
2397 ----------
2398 phi : array_like
2399 amplitude of the elliptic integral.
2400 m : array_like
2401 parameter of the elliptic integral.
2402 out : ndarray, optional
2403 Optional output array for the function values
2405 Returns
2406 -------
2407 E : scalar or ndarray
2408 Value of the elliptic integral.
2410 Notes
2411 -----
2412 Wrapper for the Cephes [1]_ routine `ellie`.
2414 Computation uses arithmetic-geometric means algorithm.
2416 The parameterization in terms of :math:`m` follows that of section
2417 17.2 in [2]_. Other parameterizations in terms of the
2418 complementary parameter :math:`1 - m`, modular angle
2419 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2420 used, so be careful that you choose the correct parameter.
2422 The Legendre E incomplete integral can be related to combinations
2423 of Carlson's symmetric integrals R_D, R_F, and R_G in multiple
2424 ways [3]_. For example, with :math:`c = \csc^2\phi`,
2426 .. math::
2427 E(\phi, m) = R_F(c-1, c-k^2, c)
2428 - \frac{1}{3} k^2 R_D(c-1, c-k^2, c) .
2430 See Also
2431 --------
2432 ellipkm1 : Complete elliptic integral of the first kind, near `m` = 1
2433 ellipk : Complete elliptic integral of the first kind
2434 ellipkinc : Incomplete elliptic integral of the first kind
2435 ellipe : Complete elliptic integral of the second kind
2436 elliprd : Symmetric elliptic integral of the second kind.
2437 elliprf : Completely-symmetric elliptic integral of the first kind.
2438 elliprg : Completely-symmetric elliptic integral of the second kind.
2440 References
2441 ----------
2442 .. [1] Cephes Mathematical Functions Library,
2443 http://www.netlib.org/cephes/
2444 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
2445 Handbook of Mathematical Functions with Formulas,
2446 Graphs, and Mathematical Tables. New York: Dover, 1972.
2447 .. [3] NIST Digital Library of Mathematical
2448 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2449 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2450 """)
2452add_newdoc("ellipj",
2453 """
2454 ellipj(u, m, out=None)
2456 Jacobian elliptic functions
2458 Calculates the Jacobian elliptic functions of parameter `m` between
2459 0 and 1, and real argument `u`.
2461 Parameters
2462 ----------
2463 m : array_like
2464 Parameter.
2465 u : array_like
2466 Argument.
2467 out : tuple of ndarray, optional
2468 Optional output arrays for the function values
2470 Returns
2471 -------
2472 sn, cn, dn, ph : 4-tuple of scalar or ndarray
2473 The returned functions::
2475 sn(u|m), cn(u|m), dn(u|m)
2477 The value `ph` is such that if `u = ellipkinc(ph, m)`,
2478 then `sn(u|m) = sin(ph)` and `cn(u|m) = cos(ph)`.
2480 Notes
2481 -----
2482 Wrapper for the Cephes [1]_ routine `ellpj`.
2484 These functions are periodic, with quarter-period on the real axis
2485 equal to the complete elliptic integral `ellipk(m)`.
2487 Relation to incomplete elliptic integral: If `u = ellipkinc(phi,m)`, then
2488 `sn(u|m) = sin(phi)`, and `cn(u|m) = cos(phi)`. The `phi` is called
2489 the amplitude of `u`.
2491 Computation is by means of the arithmetic-geometric mean algorithm,
2492 except when `m` is within 1e-9 of 0 or 1. In the latter case with `m`
2493 close to 1, the approximation applies only for `phi < pi/2`.
2495 See also
2496 --------
2497 ellipk : Complete elliptic integral of the first kind
2498 ellipkinc : Incomplete elliptic integral of the first kind
2500 References
2501 ----------
2502 .. [1] Cephes Mathematical Functions Library,
2503 http://www.netlib.org/cephes/
2504 """)
2506add_newdoc("ellipkm1",
2507 """
2508 ellipkm1(p, out=None)
2510 Complete elliptic integral of the first kind around `m` = 1
2512 This function is defined as
2514 .. math:: K(p) = \\int_0^{\\pi/2} [1 - m \\sin(t)^2]^{-1/2} dt
2516 where `m = 1 - p`.
2518 Parameters
2519 ----------
2520 p : array_like
2521 Defines the parameter of the elliptic integral as `m = 1 - p`.
2522 out : ndarray, optional
2523 Optional output array for the function values
2525 Returns
2526 -------
2527 K : scalar or ndarray
2528 Value of the elliptic integral.
2530 Notes
2531 -----
2532 Wrapper for the Cephes [1]_ routine `ellpk`.
2534 For `p <= 1`, computation uses the approximation,
2536 .. math:: K(p) \\approx P(p) - \\log(p) Q(p),
2538 where :math:`P` and :math:`Q` are tenth-order polynomials. The
2539 argument `p` is used internally rather than `m` so that the logarithmic
2540 singularity at `m = 1` will be shifted to the origin; this preserves
2541 maximum accuracy. For `p > 1`, the identity
2543 .. math:: K(p) = K(1/p)/\\sqrt(p)
2545 is used.
2547 See Also
2548 --------
2549 ellipk : Complete elliptic integral of the first kind
2550 ellipkinc : Incomplete elliptic integral of the first kind
2551 ellipe : Complete elliptic integral of the second kind
2552 ellipeinc : Incomplete elliptic integral of the second kind
2553 elliprf : Completely-symmetric elliptic integral of the first kind.
2555 References
2556 ----------
2557 .. [1] Cephes Mathematical Functions Library,
2558 http://www.netlib.org/cephes/
2559 """)
2561add_newdoc("ellipk",
2562 r"""
2563 ellipk(m, out=None)
2565 Complete elliptic integral of the first kind.
2567 This function is defined as
2569 .. math:: K(m) = \int_0^{\pi/2} [1 - m \sin(t)^2]^{-1/2} dt
2571 Parameters
2572 ----------
2573 m : array_like
2574 The parameter of the elliptic integral.
2575 out : ndarray, optional
2576 Optional output array for the function values
2578 Returns
2579 -------
2580 K : scalar or ndarray
2581 Value of the elliptic integral.
2583 Notes
2584 -----
2585 For more precision around point m = 1, use `ellipkm1`, which this
2586 function calls.
2588 The parameterization in terms of :math:`m` follows that of section
2589 17.2 in [1]_. Other parameterizations in terms of the
2590 complementary parameter :math:`1 - m`, modular angle
2591 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2592 used, so be careful that you choose the correct parameter.
2594 The Legendre K integral is related to Carlson's symmetric R_F
2595 function by [2]_:
2597 .. math:: K(m) = R_F(0, 1-k^2, 1) .
2599 See Also
2600 --------
2601 ellipkm1 : Complete elliptic integral of the first kind around m = 1
2602 ellipkinc : Incomplete elliptic integral of the first kind
2603 ellipe : Complete elliptic integral of the second kind
2604 ellipeinc : Incomplete elliptic integral of the second kind
2605 elliprf : Completely-symmetric elliptic integral of the first kind.
2607 References
2608 ----------
2609 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
2610 Handbook of Mathematical Functions with Formulas,
2611 Graphs, and Mathematical Tables. New York: Dover, 1972.
2612 .. [2] NIST Digital Library of Mathematical
2613 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2614 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2616 """)
2618add_newdoc("ellipkinc",
2619 r"""
2620 ellipkinc(phi, m, out=None)
2622 Incomplete elliptic integral of the first kind
2624 This function is defined as
2626 .. math:: K(\phi, m) = \int_0^{\phi} [1 - m \sin(t)^2]^{-1/2} dt
2628 This function is also called :math:`F(\phi, m)`.
2630 Parameters
2631 ----------
2632 phi : array_like
2633 amplitude of the elliptic integral
2634 m : array_like
2635 parameter of the elliptic integral
2636 out : ndarray, optional
2637 Optional output array for the function values
2639 Returns
2640 -------
2641 K : scalar or ndarray
2642 Value of the elliptic integral
2644 Notes
2645 -----
2646 Wrapper for the Cephes [1]_ routine `ellik`. The computation is
2647 carried out using the arithmetic-geometric mean algorithm.
2649 The parameterization in terms of :math:`m` follows that of section
2650 17.2 in [2]_. Other parameterizations in terms of the
2651 complementary parameter :math:`1 - m`, modular angle
2652 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2653 used, so be careful that you choose the correct parameter.
2655 The Legendre K incomplete integral (or F integral) is related to
2656 Carlson's symmetric R_F function [3]_.
2657 Setting :math:`c = \csc^2\phi`,
2659 .. math:: F(\phi, m) = R_F(c-1, c-k^2, c) .
2661 See Also
2662 --------
2663 ellipkm1 : Complete elliptic integral of the first kind, near `m` = 1
2664 ellipk : Complete elliptic integral of the first kind
2665 ellipe : Complete elliptic integral of the second kind
2666 ellipeinc : Incomplete elliptic integral of the second kind
2667 elliprf : Completely-symmetric elliptic integral of the first kind.
2669 References
2670 ----------
2671 .. [1] Cephes Mathematical Functions Library,
2672 http://www.netlib.org/cephes/
2673 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
2674 Handbook of Mathematical Functions with Formulas,
2675 Graphs, and Mathematical Tables. New York: Dover, 1972.
2676 .. [3] NIST Digital Library of Mathematical
2677 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2678 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2679 """)
2681add_newdoc(
2682 "elliprc",
2683 r"""
2684 elliprc(x, y, out=None)
2686 Degenerate symmetric elliptic integral.
2688 The function RC is defined as [1]_
2690 .. math::
2692 R_{\mathrm{C}}(x, y) =
2693 \frac{1}{2} \int_0^{+\infty} (t + x)^{-1/2} (t + y)^{-1} dt
2694 = R_{\mathrm{F}}(x, y, y)
2696 Parameters
2697 ----------
2698 x, y : array_like
2699 Real or complex input parameters. `x` can be any number in the
2700 complex plane cut along the negative real axis. `y` must be non-zero.
2701 out : ndarray, optional
2702 Optional output array for the function values
2704 Returns
2705 -------
2706 R : scalar or ndarray
2707 Value of the integral. If `y` is real and negative, the Cauchy
2708 principal value is returned. If both of `x` and `y` are real, the
2709 return value is real. Otherwise, the return value is complex.
2711 Notes
2712 -----
2713 RC is a degenerate case of the symmetric integral RF: ``elliprc(x, y) ==
2714 elliprf(x, y, y)``. It is an elementary function rather than an elliptic
2715 integral.
2717 The code implements Carlson's algorithm based on the duplication theorems
2718 and series expansion up to the 7th order. [2]_
2720 .. versionadded:: 1.8.0
2722 See Also
2723 --------
2724 elliprf : Completely-symmetric elliptic integral of the first kind.
2725 elliprd : Symmetric elliptic integral of the second kind.
2726 elliprg : Completely-symmetric elliptic integral of the second kind.
2727 elliprj : Symmetric elliptic integral of the third kind.
2729 References
2730 ----------
2731 .. [1] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
2732 Functions," NIST, US Dept. of Commerce.
2733 https://dlmf.nist.gov/19.16.E6
2734 .. [2] B. C. Carlson, "Numerical computation of real or complex elliptic
2735 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
2736 https://arxiv.org/abs/math/9409227
2737 https://doi.org/10.1007/BF02198293
2739 Examples
2740 --------
2741 Basic homogeneity property:
2743 >>> import numpy as np
2744 >>> from scipy.special import elliprc
2746 >>> x = 1.2 + 3.4j
2747 >>> y = 5.
2748 >>> scale = 0.3 + 0.4j
2749 >>> elliprc(scale*x, scale*y)
2750 (0.5484493976710874-0.4169557678995833j)
2752 >>> elliprc(x, y)/np.sqrt(scale)
2753 (0.5484493976710874-0.41695576789958333j)
2755 When the two arguments coincide, the integral is particularly
2756 simple:
2758 >>> x = 1.2 + 3.4j
2759 >>> elliprc(x, x)
2760 (0.4299173120614631-0.3041729818745595j)
2762 >>> 1/np.sqrt(x)
2763 (0.4299173120614631-0.30417298187455954j)
2765 Another simple case: the first argument vanishes:
2767 >>> y = 1.2 + 3.4j
2768 >>> elliprc(0, y)
2769 (0.6753125346116815-0.47779380263880866j)
2771 >>> np.pi/2/np.sqrt(y)
2772 (0.6753125346116815-0.4777938026388088j)
2774 When `x` and `y` are both positive, we can express
2775 :math:`R_C(x,y)` in terms of more elementary functions. For the
2776 case :math:`0 \le x < y`,
2778 >>> x = 3.2
2779 >>> y = 6.
2780 >>> elliprc(x, y)
2781 0.44942991498453444
2783 >>> np.arctan(np.sqrt((y-x)/x))/np.sqrt(y-x)
2784 0.44942991498453433
2786 And for the case :math:`0 \le y < x`,
2788 >>> x = 6.
2789 >>> y = 3.2
2790 >>> elliprc(x,y)
2791 0.4989837501576147
2793 >>> np.log((np.sqrt(x)+np.sqrt(x-y))/np.sqrt(y))/np.sqrt(x-y)
2794 0.49898375015761476
2796 """)
2798add_newdoc(
2799 "elliprd",
2800 r"""
2801 elliprd(x, y, z, out=None)
2803 Symmetric elliptic integral of the second kind.
2805 The function RD is defined as [1]_
2807 .. math::
2809 R_{\mathrm{D}}(x, y, z) =
2810 \frac{3}{2} \int_0^{+\infty} [(t + x) (t + y)]^{-1/2} (t + z)^{-3/2}
2811 dt
2813 Parameters
2814 ----------
2815 x, y, z : array_like
2816 Real or complex input parameters. `x` or `y` can be any number in the
2817 complex plane cut along the negative real axis, but at most one of them
2818 can be zero, while `z` must be non-zero.
2819 out : ndarray, optional
2820 Optional output array for the function values
2822 Returns
2823 -------
2824 R : scalar or ndarray
2825 Value of the integral. If all of `x`, `y`, and `z` are real, the
2826 return value is real. Otherwise, the return value is complex.
2828 Notes
2829 -----
2830 RD is a degenerate case of the elliptic integral RJ: ``elliprd(x, y, z) ==
2831 elliprj(x, y, z, z)``.
2833 The code implements Carlson's algorithm based on the duplication theorems
2834 and series expansion up to the 7th order. [2]_
2836 .. versionadded:: 1.8.0
2838 See Also
2839 --------
2840 elliprc : Degenerate symmetric elliptic integral.
2841 elliprf : Completely-symmetric elliptic integral of the first kind.
2842 elliprg : Completely-symmetric elliptic integral of the second kind.
2843 elliprj : Symmetric elliptic integral of the third kind.
2845 References
2846 ----------
2847 .. [1] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
2848 Functions," NIST, US Dept. of Commerce.
2849 https://dlmf.nist.gov/19.16.E5
2850 .. [2] B. C. Carlson, "Numerical computation of real or complex elliptic
2851 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
2852 https://arxiv.org/abs/math/9409227
2853 https://doi.org/10.1007/BF02198293
2855 Examples
2856 --------
2857 Basic homogeneity property:
2859 >>> import numpy as np
2860 >>> from scipy.special import elliprd
2862 >>> x = 1.2 + 3.4j
2863 >>> y = 5.
2864 >>> z = 6.
2865 >>> scale = 0.3 + 0.4j
2866 >>> elliprd(scale*x, scale*y, scale*z)
2867 (-0.03703043835680379-0.24500934665683802j)
2869 >>> elliprd(x, y, z)*np.power(scale, -1.5)
2870 (-0.0370304383568038-0.24500934665683805j)
2872 All three arguments coincide:
2874 >>> x = 1.2 + 3.4j
2875 >>> elliprd(x, x, x)
2876 (-0.03986825876151896-0.14051741840449586j)
2878 >>> np.power(x, -1.5)
2879 (-0.03986825876151894-0.14051741840449583j)
2881 The so-called "second lemniscate constant":
2883 >>> elliprd(0, 2, 1)/3
2884 0.5990701173677961
2886 >>> from scipy.special import gamma
2887 >>> gamma(0.75)**2/np.sqrt(2*np.pi)
2888 0.5990701173677959
2890 """)
2892add_newdoc(
2893 "elliprf",
2894 r"""
2895 elliprf(x, y, z, out=None)
2897 Completely-symmetric elliptic integral of the first kind.
2899 The function RF is defined as [1]_
2901 .. math::
2903 R_{\mathrm{F}}(x, y, z) =
2904 \frac{1}{2} \int_0^{+\infty} [(t + x) (t + y) (t + z)]^{-1/2} dt
2906 Parameters
2907 ----------
2908 x, y, z : array_like
2909 Real or complex input parameters. `x`, `y`, or `z` can be any number in
2910 the complex plane cut along the negative real axis, but at most one of
2911 them can be zero.
2912 out : ndarray, optional
2913 Optional output array for the function values
2915 Returns
2916 -------
2917 R : scalar or ndarray
2918 Value of the integral. If all of `x`, `y`, and `z` are real, the return
2919 value is real. Otherwise, the return value is complex.
2921 Notes
2922 -----
2923 The code implements Carlson's algorithm based on the duplication theorems
2924 and series expansion up to the 7th order (cf.:
2925 https://dlmf.nist.gov/19.36.i) and the AGM algorithm for the complete
2926 integral. [2]_
2928 .. versionadded:: 1.8.0
2930 See Also
2931 --------
2932 elliprc : Degenerate symmetric integral.
2933 elliprd : Symmetric elliptic integral of the second kind.
2934 elliprg : Completely-symmetric elliptic integral of the second kind.
2935 elliprj : Symmetric elliptic integral of the third kind.
2937 References
2938 ----------
2939 .. [1] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
2940 Functions," NIST, US Dept. of Commerce.
2941 https://dlmf.nist.gov/19.16.E1
2942 .. [2] B. C. Carlson, "Numerical computation of real or complex elliptic
2943 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
2944 https://arxiv.org/abs/math/9409227
2945 https://doi.org/10.1007/BF02198293
2947 Examples
2948 --------
2949 Basic homogeneity property:
2951 >>> import numpy as np
2952 >>> from scipy.special import elliprf
2954 >>> x = 1.2 + 3.4j
2955 >>> y = 5.
2956 >>> z = 6.
2957 >>> scale = 0.3 + 0.4j
2958 >>> elliprf(scale*x, scale*y, scale*z)
2959 (0.5328051227278146-0.4008623567957094j)
2961 >>> elliprf(x, y, z)/np.sqrt(scale)
2962 (0.5328051227278147-0.4008623567957095j)
2964 All three arguments coincide:
2966 >>> x = 1.2 + 3.4j
2967 >>> elliprf(x, x, x)
2968 (0.42991731206146316-0.30417298187455954j)
2970 >>> 1/np.sqrt(x)
2971 (0.4299173120614631-0.30417298187455954j)
2973 The so-called "first lemniscate constant":
2975 >>> elliprf(0, 1, 2)
2976 1.3110287771460598
2978 >>> from scipy.special import gamma
2979 >>> gamma(0.25)**2/(4*np.sqrt(2*np.pi))
2980 1.3110287771460598
2982 """)
2984add_newdoc(
2985 "elliprg",
2986 r"""
2987 elliprg(x, y, z, out=None)
2989 Completely-symmetric elliptic integral of the second kind.
2991 The function RG is defined as [1]_
2993 .. math::
2995 R_{\mathrm{G}}(x, y, z) =
2996 \frac{1}{4} \int_0^{+\infty} [(t + x) (t + y) (t + z)]^{-1/2}
2997 \left(\frac{x}{t + x} + \frac{y}{t + y} + \frac{z}{t + z}\right) t
2998 dt
3000 Parameters
3001 ----------
3002 x, y, z : array_like
3003 Real or complex input parameters. `x`, `y`, or `z` can be any number in
3004 the complex plane cut along the negative real axis.
3005 out : ndarray, optional
3006 Optional output array for the function values
3008 Returns
3009 -------
3010 R : scalar or ndarray
3011 Value of the integral. If all of `x`, `y`, and `z` are real, the return
3012 value is real. Otherwise, the return value is complex.
3014 Notes
3015 -----
3016 The implementation uses the relation [1]_
3018 .. math::
3020 2 R_{\mathrm{G}}(x, y, z) =
3021 z R_{\mathrm{F}}(x, y, z) -
3022 \frac{1}{3} (x - z) (y - z) R_{\mathrm{D}}(x, y, z) +
3023 \sqrt{\frac{x y}{z}}
3025 and the symmetry of `x`, `y`, `z` when at least one non-zero parameter can
3026 be chosen as the pivot. When one of the arguments is close to zero, the AGM
3027 method is applied instead. Other special cases are computed following Ref.
3028 [2]_
3030 .. versionadded:: 1.8.0
3032 See Also
3033 --------
3034 elliprc : Degenerate symmetric integral.
3035 elliprd : Symmetric elliptic integral of the second kind.
3036 elliprf : Completely-symmetric elliptic integral of the first kind.
3037 elliprj : Symmetric elliptic integral of the third kind.
3039 References
3040 ----------
3041 .. [1] B. C. Carlson, "Numerical computation of real or complex elliptic
3042 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
3043 https://arxiv.org/abs/math/9409227
3044 https://doi.org/10.1007/BF02198293
3045 .. [2] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
3046 Functions," NIST, US Dept. of Commerce.
3047 https://dlmf.nist.gov/19.16.E1
3048 https://dlmf.nist.gov/19.20.ii
3050 Examples
3051 --------
3052 Basic homogeneity property:
3054 >>> import numpy as np
3055 >>> from scipy.special import elliprg
3057 >>> x = 1.2 + 3.4j
3058 >>> y = 5.
3059 >>> z = 6.
3060 >>> scale = 0.3 + 0.4j
3061 >>> elliprg(scale*x, scale*y, scale*z)
3062 (1.195936862005246+0.8470988320464167j)
3064 >>> elliprg(x, y, z)*np.sqrt(scale)
3065 (1.195936862005246+0.8470988320464165j)
3067 Simplifications:
3069 >>> elliprg(0, y, y)
3070 1.756203682760182
3072 >>> 0.25*np.pi*np.sqrt(y)
3073 1.7562036827601817
3075 >>> elliprg(0, 0, z)
3076 1.224744871391589
3078 >>> 0.5*np.sqrt(z)
3079 1.224744871391589
3081 The surface area of a triaxial ellipsoid with semiaxes ``a``, ``b``, and
3082 ``c`` is given by
3084 .. math::
3086 S = 4 \pi a b c R_{\mathrm{G}}(1 / a^2, 1 / b^2, 1 / c^2).
3088 >>> def ellipsoid_area(a, b, c):
3089 ... r = 4.0 * np.pi * a * b * c
3090 ... return r * elliprg(1.0 / (a * a), 1.0 / (b * b), 1.0 / (c * c))
3091 >>> print(ellipsoid_area(1, 3, 5))
3092 108.62688289491807
3093 """)
3095add_newdoc(
3096 "elliprj",
3097 r"""
3098 elliprj(x, y, z, p, out=None)
3100 Symmetric elliptic integral of the third kind.
3102 The function RJ is defined as [1]_
3104 .. math::
3106 R_{\mathrm{J}}(x, y, z, p) =
3107 \frac{3}{2} \int_0^{+\infty} [(t + x) (t + y) (t + z)]^{-1/2}
3108 (t + p)^{-1} dt
3110 .. warning::
3111 This function should be considered experimental when the inputs are
3112 unbalanced. Check correctness with another independent implementation.
3114 Parameters
3115 ----------
3116 x, y, z, p : array_like
3117 Real or complex input parameters. `x`, `y`, or `z` are numbers in
3118 the complex plane cut along the negative real axis (subject to further
3119 constraints, see Notes), and at most one of them can be zero. `p` must
3120 be non-zero.
3121 out : ndarray, optional
3122 Optional output array for the function values
3124 Returns
3125 -------
3126 R : scalar or ndarray
3127 Value of the integral. If all of `x`, `y`, `z`, and `p` are real, the
3128 return value is real. Otherwise, the return value is complex.
3130 If `p` is real and negative, while `x`, `y`, and `z` are real,
3131 non-negative, and at most one of them is zero, the Cauchy principal
3132 value is returned. [1]_ [2]_
3134 Notes
3135 -----
3136 The code implements Carlson's algorithm based on the duplication theorems
3137 and series expansion up to the 7th order. [3]_ The algorithm is slightly
3138 different from its earlier incarnation as it appears in [1]_, in that the
3139 call to `elliprc` (or ``atan``/``atanh``, see [4]_) is no longer needed in
3140 the inner loop. Asymptotic approximations are used where arguments differ
3141 widely in the order of magnitude. [5]_
3143 The input values are subject to certain sufficient but not necessary
3144 constaints when input arguments are complex. Notably, ``x``, ``y``, and
3145 ``z`` must have non-negative real parts, unless two of them are
3146 non-negative and complex-conjugates to each other while the other is a real
3147 non-negative number. [1]_ If the inputs do not satisfy the sufficient
3148 condition described in Ref. [1]_ they are rejected outright with the output
3149 set to NaN.
3151 In the case where one of ``x``, ``y``, and ``z`` is equal to ``p``, the
3152 function ``elliprd`` should be preferred because of its less restrictive
3153 domain.
3155 .. versionadded:: 1.8.0
3157 See Also
3158 --------
3159 elliprc : Degenerate symmetric integral.
3160 elliprd : Symmetric elliptic integral of the second kind.
3161 elliprf : Completely-symmetric elliptic integral of the first kind.
3162 elliprg : Completely-symmetric elliptic integral of the second kind.
3164 References
3165 ----------
3166 .. [1] B. C. Carlson, "Numerical computation of real or complex elliptic
3167 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
3168 https://arxiv.org/abs/math/9409227
3169 https://doi.org/10.1007/BF02198293
3170 .. [2] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
3171 Functions," NIST, US Dept. of Commerce.
3172 https://dlmf.nist.gov/19.20.iii
3173 .. [3] B. C. Carlson, J. FitzSimmons, "Reduction Theorems for Elliptic
3174 Integrands with the Square Root of Two Quadratic Factors," J.
3175 Comput. Appl. Math., vol. 118, nos. 1-2, pp. 71-85, 2000.
3176 https://doi.org/10.1016/S0377-0427(00)00282-X
3177 .. [4] F. Johansson, "Numerical Evaluation of Elliptic Functions, Elliptic
3178 Integrals and Modular Forms," in J. Blumlein, C. Schneider, P.
3179 Paule, eds., "Elliptic Integrals, Elliptic Functions and Modular
3180 Forms in Quantum Field Theory," pp. 269-293, 2019 (Cham,
3181 Switzerland: Springer Nature Switzerland)
3182 https://arxiv.org/abs/1806.06725
3183 https://doi.org/10.1007/978-3-030-04480-0
3184 .. [5] B. C. Carlson, J. L. Gustafson, "Asymptotic Approximations for
3185 Symmetric Elliptic Integrals," SIAM J. Math. Anls., vol. 25, no. 2,
3186 pp. 288-303, 1994.
3187 https://arxiv.org/abs/math/9310223
3188 https://doi.org/10.1137/S0036141092228477
3190 Examples
3191 --------
3192 Basic homogeneity property:
3194 >>> import numpy as np
3195 >>> from scipy.special import elliprj
3197 >>> x = 1.2 + 3.4j
3198 >>> y = 5.
3199 >>> z = 6.
3200 >>> p = 7.
3201 >>> scale = 0.3 - 0.4j
3202 >>> elliprj(scale*x, scale*y, scale*z, scale*p)
3203 (0.10834905565679157+0.19694950747103812j)
3205 >>> elliprj(x, y, z, p)*np.power(scale, -1.5)
3206 (0.10834905565679556+0.19694950747103854j)
3208 Reduction to simpler elliptic integral:
3210 >>> elliprj(x, y, z, z)
3211 (0.08288462362195129-0.028376809745123258j)
3213 >>> from scipy.special import elliprd
3214 >>> elliprd(x, y, z)
3215 (0.08288462362195136-0.028376809745123296j)
3217 All arguments coincide:
3219 >>> elliprj(x, x, x, x)
3220 (-0.03986825876151896-0.14051741840449586j)
3222 >>> np.power(x, -1.5)
3223 (-0.03986825876151894-0.14051741840449583j)
3225 """)
3227add_newdoc("entr",
3228 r"""
3229 entr(x, out=None)
3231 Elementwise function for computing entropy.
3233 .. math:: \text{entr}(x) = \begin{cases} - x \log(x) & x > 0 \\ 0 & x = 0 \\ -\infty & \text{otherwise} \end{cases}
3235 Parameters
3236 ----------
3237 x : ndarray
3238 Input array.
3239 out : ndarray, optional
3240 Optional output array for the function values
3242 Returns
3243 -------
3244 res : scalar or ndarray
3245 The value of the elementwise entropy function at the given points `x`.
3247 See Also
3248 --------
3249 kl_div, rel_entr, scipy.stats.entropy
3251 Notes
3252 -----
3253 .. versionadded:: 0.15.0
3255 This function is concave.
3257 The origin of this function is in convex programming; see [1]_.
3258 Given a probability distribution :math:`p_1, \ldots, p_n`,
3259 the definition of entropy in the context of *information theory* is
3261 .. math::
3263 \sum_{i = 1}^n \mathrm{entr}(p_i).
3265 To compute the latter quantity, use `scipy.stats.entropy`.
3267 References
3268 ----------
3269 .. [1] Boyd, Stephen and Lieven Vandenberghe. *Convex optimization*.
3270 Cambridge University Press, 2004.
3271 :doi:`https://doi.org/10.1017/CBO9780511804441`
3273 """)
3275add_newdoc("erf",
3276 """
3277 erf(z, out=None)
3279 Returns the error function of complex argument.
3281 It is defined as ``2/sqrt(pi)*integral(exp(-t**2), t=0..z)``.
3283 Parameters
3284 ----------
3285 x : ndarray
3286 Input array.
3287 out : ndarray, optional
3288 Optional output array for the function values
3290 Returns
3291 -------
3292 res : scalar or ndarray
3293 The values of the error function at the given points `x`.
3295 See Also
3296 --------
3297 erfc, erfinv, erfcinv, wofz, erfcx, erfi
3299 Notes
3300 -----
3301 The cumulative of the unit normal distribution is given by
3302 ``Phi(z) = 1/2[1 + erf(z/sqrt(2))]``.
3304 References
3305 ----------
3306 .. [1] https://en.wikipedia.org/wiki/Error_function
3307 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
3308 Handbook of Mathematical Functions with Formulas,
3309 Graphs, and Mathematical Tables. New York: Dover,
3310 1972. http://www.math.sfu.ca/~cbm/aands/page_297.htm
3311 .. [3] Steven G. Johnson, Faddeeva W function implementation.
3312 http://ab-initio.mit.edu/Faddeeva
3314 Examples
3315 --------
3316 >>> import numpy as np
3317 >>> from scipy import special
3318 >>> import matplotlib.pyplot as plt
3319 >>> x = np.linspace(-3, 3)
3320 >>> plt.plot(x, special.erf(x))
3321 >>> plt.xlabel('$x$')
3322 >>> plt.ylabel('$erf(x)$')
3323 >>> plt.show()
3325 """)
3327add_newdoc("erfc",
3328 """
3329 erfc(x, out=None)
3331 Complementary error function, ``1 - erf(x)``.
3333 Parameters
3334 ----------
3335 x : array_like
3336 Real or complex valued argument
3337 out : ndarray, optional
3338 Optional output array for the function results
3340 Returns
3341 -------
3342 scalar or ndarray
3343 Values of the complementary error function
3345 See Also
3346 --------
3347 erf, erfi, erfcx, dawsn, wofz
3349 References
3350 ----------
3351 .. [1] Steven G. Johnson, Faddeeva W function implementation.
3352 http://ab-initio.mit.edu/Faddeeva
3354 Examples
3355 --------
3356 >>> import numpy as np
3357 >>> from scipy import special
3358 >>> import matplotlib.pyplot as plt
3359 >>> x = np.linspace(-3, 3)
3360 >>> plt.plot(x, special.erfc(x))
3361 >>> plt.xlabel('$x$')
3362 >>> plt.ylabel('$erfc(x)$')
3363 >>> plt.show()
3365 """)
3367add_newdoc("erfi",
3368 """
3369 erfi(z, out=None)
3371 Imaginary error function, ``-i erf(i z)``.
3373 Parameters
3374 ----------
3375 z : array_like
3376 Real or complex valued argument
3377 out : ndarray, optional
3378 Optional output array for the function results
3380 Returns
3381 -------
3382 scalar or ndarray
3383 Values of the imaginary error function
3385 See Also
3386 --------
3387 erf, erfc, erfcx, dawsn, wofz
3389 Notes
3390 -----
3392 .. versionadded:: 0.12.0
3394 References
3395 ----------
3396 .. [1] Steven G. Johnson, Faddeeva W function implementation.
3397 http://ab-initio.mit.edu/Faddeeva
3399 Examples
3400 --------
3401 >>> import numpy as np
3402 >>> from scipy import special
3403 >>> import matplotlib.pyplot as plt
3404 >>> x = np.linspace(-3, 3)
3405 >>> plt.plot(x, special.erfi(x))
3406 >>> plt.xlabel('$x$')
3407 >>> plt.ylabel('$erfi(x)$')
3408 >>> plt.show()
3410 """)
3412add_newdoc("erfcx",
3413 """
3414 erfcx(x, out=None)
3416 Scaled complementary error function, ``exp(x**2) * erfc(x)``.
3418 Parameters
3419 ----------
3420 x : array_like
3421 Real or complex valued argument
3422 out : ndarray, optional
3423 Optional output array for the function results
3425 Returns
3426 -------
3427 scalar or ndarray
3428 Values of the scaled complementary error function
3431 See Also
3432 --------
3433 erf, erfc, erfi, dawsn, wofz
3435 Notes
3436 -----
3438 .. versionadded:: 0.12.0
3440 References
3441 ----------
3442 .. [1] Steven G. Johnson, Faddeeva W function implementation.
3443 http://ab-initio.mit.edu/Faddeeva
3445 Examples
3446 --------
3447 >>> import numpy as np
3448 >>> from scipy import special
3449 >>> import matplotlib.pyplot as plt
3450 >>> x = np.linspace(-3, 3)
3451 >>> plt.plot(x, special.erfcx(x))
3452 >>> plt.xlabel('$x$')
3453 >>> plt.ylabel('$erfcx(x)$')
3454 >>> plt.show()
3456 """)
3458add_newdoc(
3459 "erfinv",
3460 """
3461 erfinv(y, out=None)
3463 Inverse of the error function.
3465 Computes the inverse of the error function.
3467 In the complex domain, there is no unique complex number w satisfying
3468 erf(w)=z. This indicates a true inverse function would be multivalued.
3469 When the domain restricts to the real, -1 < x < 1, there is a unique real
3470 number satisfying erf(erfinv(x)) = x.
3472 Parameters
3473 ----------
3474 y : ndarray
3475 Argument at which to evaluate. Domain: [-1, 1]
3476 out : ndarray, optional
3477 Optional output array for the function values
3479 Returns
3480 -------
3481 erfinv : scalar or ndarray
3482 The inverse of erf of y, element-wise
3484 See Also
3485 --------
3486 erf : Error function of a complex argument
3487 erfc : Complementary error function, ``1 - erf(x)``
3488 erfcinv : Inverse of the complementary error function
3490 Examples
3491 --------
3492 >>> import numpy as np
3493 >>> import matplotlib.pyplot as plt
3494 >>> from scipy.special import erfinv, erf
3496 >>> erfinv(0.5)
3497 0.4769362762044699
3499 >>> y = np.linspace(-1.0, 1.0, num=9)
3500 >>> x = erfinv(y)
3501 >>> x
3502 array([ -inf, -0.81341985, -0.47693628, -0.22531206, 0. ,
3503 0.22531206, 0.47693628, 0.81341985, inf])
3505 Verify that ``erf(erfinv(y))`` is ``y``.
3507 >>> erf(x)
3508 array([-1. , -0.75, -0.5 , -0.25, 0. , 0.25, 0.5 , 0.75, 1. ])
3510 Plot the function:
3512 >>> y = np.linspace(-1, 1, 200)
3513 >>> fig, ax = plt.subplots()
3514 >>> ax.plot(y, erfinv(y))
3515 >>> ax.grid(True)
3516 >>> ax.set_xlabel('y')
3517 >>> ax.set_title('erfinv(y)')
3518 >>> plt.show()
3520 """)
3522add_newdoc(
3523 "erfcinv",
3524 """
3525 erfcinv(y, out=None)
3527 Inverse of the complementary error function.
3529 Computes the inverse of the complementary error function.
3531 In the complex domain, there is no unique complex number w satisfying
3532 erfc(w)=z. This indicates a true inverse function would be multivalued.
3533 When the domain restricts to the real, 0 < x < 2, there is a unique real
3534 number satisfying erfc(erfcinv(x)) = erfcinv(erfc(x)).
3536 It is related to inverse of the error function by erfcinv(1-x) = erfinv(x)
3538 Parameters
3539 ----------
3540 y : ndarray
3541 Argument at which to evaluate. Domain: [0, 2]
3542 out : ndarray, optional
3543 Optional output array for the function values
3545 Returns
3546 -------
3547 erfcinv : scalar or ndarray
3548 The inverse of erfc of y, element-wise
3550 See Also
3551 --------
3552 erf : Error function of a complex argument
3553 erfc : Complementary error function, ``1 - erf(x)``
3554 erfinv : Inverse of the error function
3556 Examples
3557 --------
3558 >>> import numpy as np
3559 >>> import matplotlib.pyplot as plt
3560 >>> from scipy.special import erfcinv
3562 >>> erfcinv(0.5)
3563 0.4769362762044699
3565 >>> y = np.linspace(0.0, 2.0, num=11)
3566 >>> erfcinv(y)
3567 array([ inf, 0.9061938 , 0.59511608, 0.37080716, 0.17914345,
3568 -0. , -0.17914345, -0.37080716, -0.59511608, -0.9061938 ,
3569 -inf])
3571 Plot the function:
3573 >>> y = np.linspace(0, 2, 200)
3574 >>> fig, ax = plt.subplots()
3575 >>> ax.plot(y, erfcinv(y))
3576 >>> ax.grid(True)
3577 >>> ax.set_xlabel('y')
3578 >>> ax.set_title('erfcinv(y)')
3579 >>> plt.show()
3581 """)
3583add_newdoc("eval_jacobi",
3584 r"""
3585 eval_jacobi(n, alpha, beta, x, out=None)
3587 Evaluate Jacobi polynomial at a point.
3589 The Jacobi polynomials can be defined via the Gauss hypergeometric
3590 function :math:`{}_2F_1` as
3592 .. math::
3594 P_n^{(\alpha, \beta)}(x) = \frac{(\alpha + 1)_n}{\Gamma(n + 1)}
3595 {}_2F_1(-n, 1 + \alpha + \beta + n; \alpha + 1; (1 - z)/2)
3597 where :math:`(\cdot)_n` is the Pochhammer symbol; see `poch`. When
3598 :math:`n` is an integer the result is a polynomial of degree
3599 :math:`n`. See 22.5.42 in [AS]_ for details.
3601 Parameters
3602 ----------
3603 n : array_like
3604 Degree of the polynomial. If not an integer the result is
3605 determined via the relation to the Gauss hypergeometric
3606 function.
3607 alpha : array_like
3608 Parameter
3609 beta : array_like
3610 Parameter
3611 x : array_like
3612 Points at which to evaluate the polynomial
3613 out : ndarray, optional
3614 Optional output array for the function values
3616 Returns
3617 -------
3618 P : scalar or ndarray
3619 Values of the Jacobi polynomial
3621 See Also
3622 --------
3623 roots_jacobi : roots and quadrature weights of Jacobi polynomials
3624 jacobi : Jacobi polynomial object
3625 hyp2f1 : Gauss hypergeometric function
3627 References
3628 ----------
3629 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3630 Handbook of Mathematical Functions with Formulas,
3631 Graphs, and Mathematical Tables. New York: Dover, 1972.
3633 """)
3635add_newdoc("eval_sh_jacobi",
3636 r"""
3637 eval_sh_jacobi(n, p, q, x, out=None)
3639 Evaluate shifted Jacobi polynomial at a point.
3641 Defined by
3643 .. math::
3645 G_n^{(p, q)}(x)
3646 = \binom{2n + p - 1}{n}^{-1} P_n^{(p - q, q - 1)}(2x - 1),
3648 where :math:`P_n^{(\cdot, \cdot)}` is the n-th Jacobi
3649 polynomial. See 22.5.2 in [AS]_ for details.
3651 Parameters
3652 ----------
3653 n : int
3654 Degree of the polynomial. If not an integer, the result is
3655 determined via the relation to `binom` and `eval_jacobi`.
3656 p : float
3657 Parameter
3658 q : float
3659 Parameter
3660 out : ndarray, optional
3661 Optional output array for the function values
3663 Returns
3664 -------
3665 G : scalar or ndarray
3666 Values of the shifted Jacobi polynomial.
3668 See Also
3669 --------
3670 roots_sh_jacobi : roots and quadrature weights of shifted Jacobi
3671 polynomials
3672 sh_jacobi : shifted Jacobi polynomial object
3673 eval_jacobi : evaluate Jacobi polynomials
3675 References
3676 ----------
3677 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3678 Handbook of Mathematical Functions with Formulas,
3679 Graphs, and Mathematical Tables. New York: Dover, 1972.
3681 """)
3683add_newdoc("eval_gegenbauer",
3684 r"""
3685 eval_gegenbauer(n, alpha, x, out=None)
3687 Evaluate Gegenbauer polynomial at a point.
3689 The Gegenbauer polynomials can be defined via the Gauss
3690 hypergeometric function :math:`{}_2F_1` as
3692 .. math::
3694 C_n^{(\alpha)} = \frac{(2\alpha)_n}{\Gamma(n + 1)}
3695 {}_2F_1(-n, 2\alpha + n; \alpha + 1/2; (1 - z)/2).
3697 When :math:`n` is an integer the result is a polynomial of degree
3698 :math:`n`. See 22.5.46 in [AS]_ for details.
3700 Parameters
3701 ----------
3702 n : array_like
3703 Degree of the polynomial. If not an integer, the result is
3704 determined via the relation to the Gauss hypergeometric
3705 function.
3706 alpha : array_like
3707 Parameter
3708 x : array_like
3709 Points at which to evaluate the Gegenbauer polynomial
3710 out : ndarray, optional
3711 Optional output array for the function values
3713 Returns
3714 -------
3715 C : scalar or ndarray
3716 Values of the Gegenbauer polynomial
3718 See Also
3719 --------
3720 roots_gegenbauer : roots and quadrature weights of Gegenbauer
3721 polynomials
3722 gegenbauer : Gegenbauer polynomial object
3723 hyp2f1 : Gauss hypergeometric function
3725 References
3726 ----------
3727 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3728 Handbook of Mathematical Functions with Formulas,
3729 Graphs, and Mathematical Tables. New York: Dover, 1972.
3731 """)
3733add_newdoc("eval_chebyt",
3734 r"""
3735 eval_chebyt(n, x, out=None)
3737 Evaluate Chebyshev polynomial of the first kind at a point.
3739 The Chebyshev polynomials of the first kind can be defined via the
3740 Gauss hypergeometric function :math:`{}_2F_1` as
3742 .. math::
3744 T_n(x) = {}_2F_1(n, -n; 1/2; (1 - x)/2).
3746 When :math:`n` is an integer the result is a polynomial of degree
3747 :math:`n`. See 22.5.47 in [AS]_ for details.
3749 Parameters
3750 ----------
3751 n : array_like
3752 Degree of the polynomial. If not an integer, the result is
3753 determined via the relation to the Gauss hypergeometric
3754 function.
3755 x : array_like
3756 Points at which to evaluate the Chebyshev polynomial
3757 out : ndarray, optional
3758 Optional output array for the function values
3760 Returns
3761 -------
3762 T : scalar or ndarray
3763 Values of the Chebyshev polynomial
3765 See Also
3766 --------
3767 roots_chebyt : roots and quadrature weights of Chebyshev
3768 polynomials of the first kind
3769 chebyu : Chebychev polynomial object
3770 eval_chebyu : evaluate Chebyshev polynomials of the second kind
3771 hyp2f1 : Gauss hypergeometric function
3772 numpy.polynomial.chebyshev.Chebyshev : Chebyshev series
3774 Notes
3775 -----
3776 This routine is numerically stable for `x` in ``[-1, 1]`` at least
3777 up to order ``10000``.
3779 References
3780 ----------
3781 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3782 Handbook of Mathematical Functions with Formulas,
3783 Graphs, and Mathematical Tables. New York: Dover, 1972.
3785 """)
3787add_newdoc("eval_chebyu",
3788 r"""
3789 eval_chebyu(n, x, out=None)
3791 Evaluate Chebyshev polynomial of the second kind at a point.
3793 The Chebyshev polynomials of the second kind can be defined via
3794 the Gauss hypergeometric function :math:`{}_2F_1` as
3796 .. math::
3798 U_n(x) = (n + 1) {}_2F_1(-n, n + 2; 3/2; (1 - x)/2).
3800 When :math:`n` is an integer the result is a polynomial of degree
3801 :math:`n`. See 22.5.48 in [AS]_ for details.
3803 Parameters
3804 ----------
3805 n : array_like
3806 Degree of the polynomial. If not an integer, the result is
3807 determined via the relation to the Gauss hypergeometric
3808 function.
3809 x : array_like
3810 Points at which to evaluate the Chebyshev polynomial
3811 out : ndarray, optional
3812 Optional output array for the function values
3814 Returns
3815 -------
3816 U : scalar or ndarray
3817 Values of the Chebyshev polynomial
3819 See Also
3820 --------
3821 roots_chebyu : roots and quadrature weights of Chebyshev
3822 polynomials of the second kind
3823 chebyu : Chebyshev polynomial object
3824 eval_chebyt : evaluate Chebyshev polynomials of the first kind
3825 hyp2f1 : Gauss hypergeometric function
3827 References
3828 ----------
3829 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3830 Handbook of Mathematical Functions with Formulas,
3831 Graphs, and Mathematical Tables. New York: Dover, 1972.
3833 """)
3835add_newdoc("eval_chebys",
3836 r"""
3837 eval_chebys(n, x, out=None)
3839 Evaluate Chebyshev polynomial of the second kind on [-2, 2] at a
3840 point.
3842 These polynomials are defined as
3844 .. math::
3846 S_n(x) = U_n(x/2)
3848 where :math:`U_n` is a Chebyshev polynomial of the second
3849 kind. See 22.5.13 in [AS]_ for details.
3851 Parameters
3852 ----------
3853 n : array_like
3854 Degree of the polynomial. If not an integer, the result is
3855 determined via the relation to `eval_chebyu`.
3856 x : array_like
3857 Points at which to evaluate the Chebyshev polynomial
3858 out : ndarray, optional
3859 Optional output array for the function values
3861 Returns
3862 -------
3863 S : scalar or ndarray
3864 Values of the Chebyshev polynomial
3866 See Also
3867 --------
3868 roots_chebys : roots and quadrature weights of Chebyshev
3869 polynomials of the second kind on [-2, 2]
3870 chebys : Chebyshev polynomial object
3871 eval_chebyu : evaluate Chebyshev polynomials of the second kind
3873 References
3874 ----------
3875 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3876 Handbook of Mathematical Functions with Formulas,
3877 Graphs, and Mathematical Tables. New York: Dover, 1972.
3879 Examples
3880 --------
3881 >>> import numpy as np
3882 >>> import scipy.special as sc
3884 They are a scaled version of the Chebyshev polynomials of the
3885 second kind.
3887 >>> x = np.linspace(-2, 2, 6)
3888 >>> sc.eval_chebys(3, x)
3889 array([-4. , 0.672, 0.736, -0.736, -0.672, 4. ])
3890 >>> sc.eval_chebyu(3, x / 2)
3891 array([-4. , 0.672, 0.736, -0.736, -0.672, 4. ])
3893 """)
3895add_newdoc("eval_chebyc",
3896 r"""
3897 eval_chebyc(n, x, out=None)
3899 Evaluate Chebyshev polynomial of the first kind on [-2, 2] at a
3900 point.
3902 These polynomials are defined as
3904 .. math::
3906 C_n(x) = 2 T_n(x/2)
3908 where :math:`T_n` is a Chebyshev polynomial of the first kind. See
3909 22.5.11 in [AS]_ for details.
3911 Parameters
3912 ----------
3913 n : array_like
3914 Degree of the polynomial. If not an integer, the result is
3915 determined via the relation to `eval_chebyt`.
3916 x : array_like
3917 Points at which to evaluate the Chebyshev polynomial
3918 out : ndarray, optional
3919 Optional output array for the function values
3921 Returns
3922 -------
3923 C : scalar or ndarray
3924 Values of the Chebyshev polynomial
3926 See Also
3927 --------
3928 roots_chebyc : roots and quadrature weights of Chebyshev
3929 polynomials of the first kind on [-2, 2]
3930 chebyc : Chebyshev polynomial object
3931 numpy.polynomial.chebyshev.Chebyshev : Chebyshev series
3932 eval_chebyt : evaluate Chebycshev polynomials of the first kind
3934 References
3935 ----------
3936 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3937 Handbook of Mathematical Functions with Formulas,
3938 Graphs, and Mathematical Tables. New York: Dover, 1972.
3940 Examples
3941 --------
3942 >>> import numpy as np
3943 >>> import scipy.special as sc
3945 They are a scaled version of the Chebyshev polynomials of the
3946 first kind.
3948 >>> x = np.linspace(-2, 2, 6)
3949 >>> sc.eval_chebyc(3, x)
3950 array([-2. , 1.872, 1.136, -1.136, -1.872, 2. ])
3951 >>> 2 * sc.eval_chebyt(3, x / 2)
3952 array([-2. , 1.872, 1.136, -1.136, -1.872, 2. ])
3954 """)
3956add_newdoc("eval_sh_chebyt",
3957 r"""
3958 eval_sh_chebyt(n, x, out=None)
3960 Evaluate shifted Chebyshev polynomial of the first kind at a
3961 point.
3963 These polynomials are defined as
3965 .. math::
3967 T_n^*(x) = T_n(2x - 1)
3969 where :math:`T_n` is a Chebyshev polynomial of the first kind. See
3970 22.5.14 in [AS]_ for details.
3972 Parameters
3973 ----------
3974 n : array_like
3975 Degree of the polynomial. If not an integer, the result is
3976 determined via the relation to `eval_chebyt`.
3977 x : array_like
3978 Points at which to evaluate the shifted Chebyshev polynomial
3979 out : ndarray, optional
3980 Optional output array for the function values
3982 Returns
3983 -------
3984 T : scalar or ndarray
3985 Values of the shifted Chebyshev polynomial
3987 See Also
3988 --------
3989 roots_sh_chebyt : roots and quadrature weights of shifted
3990 Chebyshev polynomials of the first kind
3991 sh_chebyt : shifted Chebyshev polynomial object
3992 eval_chebyt : evaluate Chebyshev polynomials of the first kind
3993 numpy.polynomial.chebyshev.Chebyshev : Chebyshev series
3995 References
3996 ----------
3997 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3998 Handbook of Mathematical Functions with Formulas,
3999 Graphs, and Mathematical Tables. New York: Dover, 1972.
4001 """)
4003add_newdoc("eval_sh_chebyu",
4004 r"""
4005 eval_sh_chebyu(n, x, out=None)
4007 Evaluate shifted Chebyshev polynomial of the second kind at a
4008 point.
4010 These polynomials are defined as
4012 .. math::
4014 U_n^*(x) = U_n(2x - 1)
4016 where :math:`U_n` is a Chebyshev polynomial of the first kind. See
4017 22.5.15 in [AS]_ for details.
4019 Parameters
4020 ----------
4021 n : array_like
4022 Degree of the polynomial. If not an integer, the result is
4023 determined via the relation to `eval_chebyu`.
4024 x : array_like
4025 Points at which to evaluate the shifted Chebyshev polynomial
4026 out : ndarray, optional
4027 Optional output array for the function values
4029 Returns
4030 -------
4031 U : scalar or ndarray
4032 Values of the shifted Chebyshev polynomial
4034 See Also
4035 --------
4036 roots_sh_chebyu : roots and quadrature weights of shifted
4037 Chebychev polynomials of the second kind
4038 sh_chebyu : shifted Chebyshev polynomial object
4039 eval_chebyu : evaluate Chebyshev polynomials of the second kind
4041 References
4042 ----------
4043 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4044 Handbook of Mathematical Functions with Formulas,
4045 Graphs, and Mathematical Tables. New York: Dover, 1972.
4047 """)
4049add_newdoc("eval_legendre",
4050 r"""
4051 eval_legendre(n, x, out=None)
4053 Evaluate Legendre polynomial at a point.
4055 The Legendre polynomials can be defined via the Gauss
4056 hypergeometric function :math:`{}_2F_1` as
4058 .. math::
4060 P_n(x) = {}_2F_1(-n, n + 1; 1; (1 - x)/2).
4062 When :math:`n` is an integer the result is a polynomial of degree
4063 :math:`n`. See 22.5.49 in [AS]_ for details.
4065 Parameters
4066 ----------
4067 n : array_like
4068 Degree of the polynomial. If not an integer, the result is
4069 determined via the relation to the Gauss hypergeometric
4070 function.
4071 x : array_like
4072 Points at which to evaluate the Legendre polynomial
4073 out : ndarray, optional
4074 Optional output array for the function values
4076 Returns
4077 -------
4078 P : scalar or ndarray
4079 Values of the Legendre polynomial
4081 See Also
4082 --------
4083 roots_legendre : roots and quadrature weights of Legendre
4084 polynomials
4085 legendre : Legendre polynomial object
4086 hyp2f1 : Gauss hypergeometric function
4087 numpy.polynomial.legendre.Legendre : Legendre series
4089 References
4090 ----------
4091 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4092 Handbook of Mathematical Functions with Formulas,
4093 Graphs, and Mathematical Tables. New York: Dover, 1972.
4095 Examples
4096 --------
4097 >>> import numpy as np
4098 >>> from scipy.special import eval_legendre
4100 Evaluate the zero-order Legendre polynomial at x = 0
4102 >>> eval_legendre(0, 0)
4103 1.0
4105 Evaluate the first-order Legendre polynomial between -1 and 1
4107 >>> X = np.linspace(-1, 1, 5) # Domain of Legendre polynomials
4108 >>> eval_legendre(1, X)
4109 array([-1. , -0.5, 0. , 0.5, 1. ])
4111 Evaluate Legendre polynomials of order 0 through 4 at x = 0
4113 >>> N = range(0, 5)
4114 >>> eval_legendre(N, 0)
4115 array([ 1. , 0. , -0.5 , 0. , 0.375])
4117 Plot Legendre polynomials of order 0 through 4
4119 >>> X = np.linspace(-1, 1)
4121 >>> import matplotlib.pyplot as plt
4122 >>> for n in range(0, 5):
4123 ... y = eval_legendre(n, X)
4124 ... plt.plot(X, y, label=r'$P_{}(x)$'.format(n))
4126 >>> plt.title("Legendre Polynomials")
4127 >>> plt.xlabel("x")
4128 >>> plt.ylabel(r'$P_n(x)$')
4129 >>> plt.legend(loc='lower right')
4130 >>> plt.show()
4132 """)
4134add_newdoc("eval_sh_legendre",
4135 r"""
4136 eval_sh_legendre(n, x, out=None)
4138 Evaluate shifted Legendre polynomial at a point.
4140 These polynomials are defined as
4142 .. math::
4144 P_n^*(x) = P_n(2x - 1)
4146 where :math:`P_n` is a Legendre polynomial. See 2.2.11 in [AS]_
4147 for details.
4149 Parameters
4150 ----------
4151 n : array_like
4152 Degree of the polynomial. If not an integer, the value is
4153 determined via the relation to `eval_legendre`.
4154 x : array_like
4155 Points at which to evaluate the shifted Legendre polynomial
4156 out : ndarray, optional
4157 Optional output array for the function values
4159 Returns
4160 -------
4161 P : scalar or ndarray
4162 Values of the shifted Legendre polynomial
4164 See Also
4165 --------
4166 roots_sh_legendre : roots and quadrature weights of shifted
4167 Legendre polynomials
4168 sh_legendre : shifted Legendre polynomial object
4169 eval_legendre : evaluate Legendre polynomials
4170 numpy.polynomial.legendre.Legendre : Legendre series
4172 References
4173 ----------
4174 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4175 Handbook of Mathematical Functions with Formulas,
4176 Graphs, and Mathematical Tables. New York: Dover, 1972.
4178 """)
4180add_newdoc("eval_genlaguerre",
4181 r"""
4182 eval_genlaguerre(n, alpha, x, out=None)
4184 Evaluate generalized Laguerre polynomial at a point.
4186 The generalized Laguerre polynomials can be defined via the
4187 confluent hypergeometric function :math:`{}_1F_1` as
4189 .. math::
4191 L_n^{(\alpha)}(x) = \binom{n + \alpha}{n}
4192 {}_1F_1(-n, \alpha + 1, x).
4194 When :math:`n` is an integer the result is a polynomial of degree
4195 :math:`n`. See 22.5.54 in [AS]_ for details. The Laguerre
4196 polynomials are the special case where :math:`\alpha = 0`.
4198 Parameters
4199 ----------
4200 n : array_like
4201 Degree of the polynomial. If not an integer, the result is
4202 determined via the relation to the confluent hypergeometric
4203 function.
4204 alpha : array_like
4205 Parameter; must have ``alpha > -1``
4206 x : array_like
4207 Points at which to evaluate the generalized Laguerre
4208 polynomial
4209 out : ndarray, optional
4210 Optional output array for the function values
4212 Returns
4213 -------
4214 L : scalar or ndarray
4215 Values of the generalized Laguerre polynomial
4217 See Also
4218 --------
4219 roots_genlaguerre : roots and quadrature weights of generalized
4220 Laguerre polynomials
4221 genlaguerre : generalized Laguerre polynomial object
4222 hyp1f1 : confluent hypergeometric function
4223 eval_laguerre : evaluate Laguerre polynomials
4225 References
4226 ----------
4227 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4228 Handbook of Mathematical Functions with Formulas,
4229 Graphs, and Mathematical Tables. New York: Dover, 1972.
4231 """)
4233add_newdoc("eval_laguerre",
4234 r"""
4235 eval_laguerre(n, x, out=None)
4237 Evaluate Laguerre polynomial at a point.
4239 The Laguerre polynomials can be defined via the confluent
4240 hypergeometric function :math:`{}_1F_1` as
4242 .. math::
4244 L_n(x) = {}_1F_1(-n, 1, x).
4246 See 22.5.16 and 22.5.54 in [AS]_ for details. When :math:`n` is an
4247 integer the result is a polynomial of degree :math:`n`.
4249 Parameters
4250 ----------
4251 n : array_like
4252 Degree of the polynomial. If not an integer the result is
4253 determined via the relation to the confluent hypergeometric
4254 function.
4255 x : array_like
4256 Points at which to evaluate the Laguerre polynomial
4257 out : ndarray, optional
4258 Optional output array for the function values
4260 Returns
4261 -------
4262 L : scalar or ndarray
4263 Values of the Laguerre polynomial
4265 See Also
4266 --------
4267 roots_laguerre : roots and quadrature weights of Laguerre
4268 polynomials
4269 laguerre : Laguerre polynomial object
4270 numpy.polynomial.laguerre.Laguerre : Laguerre series
4271 eval_genlaguerre : evaluate generalized Laguerre polynomials
4273 References
4274 ----------
4275 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4276 Handbook of Mathematical Functions with Formulas,
4277 Graphs, and Mathematical Tables. New York: Dover, 1972.
4279 """)
4281add_newdoc("eval_hermite",
4282 r"""
4283 eval_hermite(n, x, out=None)
4285 Evaluate physicist's Hermite polynomial at a point.
4287 Defined by
4289 .. math::
4291 H_n(x) = (-1)^n e^{x^2} \frac{d^n}{dx^n} e^{-x^2};
4293 :math:`H_n` is a polynomial of degree :math:`n`. See 22.11.7 in
4294 [AS]_ for details.
4296 Parameters
4297 ----------
4298 n : array_like
4299 Degree of the polynomial
4300 x : array_like
4301 Points at which to evaluate the Hermite polynomial
4302 out : ndarray, optional
4303 Optional output array for the function values
4305 Returns
4306 -------
4307 H : scalar or ndarray
4308 Values of the Hermite polynomial
4310 See Also
4311 --------
4312 roots_hermite : roots and quadrature weights of physicist's
4313 Hermite polynomials
4314 hermite : physicist's Hermite polynomial object
4315 numpy.polynomial.hermite.Hermite : Physicist's Hermite series
4316 eval_hermitenorm : evaluate Probabilist's Hermite polynomials
4318 References
4319 ----------
4320 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4321 Handbook of Mathematical Functions with Formulas,
4322 Graphs, and Mathematical Tables. New York: Dover, 1972.
4324 """)
4326add_newdoc("eval_hermitenorm",
4327 r"""
4328 eval_hermitenorm(n, x, out=None)
4330 Evaluate probabilist's (normalized) Hermite polynomial at a
4331 point.
4333 Defined by
4335 .. math::
4337 He_n(x) = (-1)^n e^{x^2/2} \frac{d^n}{dx^n} e^{-x^2/2};
4339 :math:`He_n` is a polynomial of degree :math:`n`. See 22.11.8 in
4340 [AS]_ for details.
4342 Parameters
4343 ----------
4344 n : array_like
4345 Degree of the polynomial
4346 x : array_like
4347 Points at which to evaluate the Hermite polynomial
4348 out : ndarray, optional
4349 Optional output array for the function values
4351 Returns
4352 -------
4353 He : scalar or ndarray
4354 Values of the Hermite polynomial
4356 See Also
4357 --------
4358 roots_hermitenorm : roots and quadrature weights of probabilist's
4359 Hermite polynomials
4360 hermitenorm : probabilist's Hermite polynomial object
4361 numpy.polynomial.hermite_e.HermiteE : Probabilist's Hermite series
4362 eval_hermite : evaluate physicist's Hermite polynomials
4364 References
4365 ----------
4366 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4367 Handbook of Mathematical Functions with Formulas,
4368 Graphs, and Mathematical Tables. New York: Dover, 1972.
4370 """)
4372add_newdoc("exp1",
4373 r"""
4374 exp1(z, out=None)
4376 Exponential integral E1.
4378 For complex :math:`z \ne 0` the exponential integral can be defined as
4379 [1]_
4381 .. math::
4383 E_1(z) = \int_z^\infty \frac{e^{-t}}{t} dt,
4385 where the path of the integral does not cross the negative real
4386 axis or pass through the origin.
4388 Parameters
4389 ----------
4390 z: array_like
4391 Real or complex argument.
4392 out : ndarray, optional
4393 Optional output array for the function results
4395 Returns
4396 -------
4397 scalar or ndarray
4398 Values of the exponential integral E1
4400 See Also
4401 --------
4402 expi : exponential integral :math:`Ei`
4403 expn : generalization of :math:`E_1`
4405 Notes
4406 -----
4407 For :math:`x > 0` it is related to the exponential integral
4408 :math:`Ei` (see `expi`) via the relation
4410 .. math::
4412 E_1(x) = -Ei(-x).
4414 References
4415 ----------
4416 .. [1] Digital Library of Mathematical Functions, 6.2.1
4417 https://dlmf.nist.gov/6.2#E1
4419 Examples
4420 --------
4421 >>> import numpy as np
4422 >>> import scipy.special as sc
4424 It has a pole at 0.
4426 >>> sc.exp1(0)
4427 inf
4429 It has a branch cut on the negative real axis.
4431 >>> sc.exp1(-1)
4432 nan
4433 >>> sc.exp1(complex(-1, 0))
4434 (-1.8951178163559368-3.141592653589793j)
4435 >>> sc.exp1(complex(-1, -0.0))
4436 (-1.8951178163559368+3.141592653589793j)
4438 It approaches 0 along the positive real axis.
4440 >>> sc.exp1([1, 10, 100, 1000])
4441 array([2.19383934e-01, 4.15696893e-06, 3.68359776e-46, 0.00000000e+00])
4443 It is related to `expi`.
4445 >>> x = np.array([1, 2, 3, 4])
4446 >>> sc.exp1(x)
4447 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4448 >>> -sc.expi(-x)
4449 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4451 """)
4454add_newdoc(
4455 "_scaled_exp1",
4456 """
4457 _scaled_exp1(x, out=None):
4459 Compute the scaled exponential integral.
4461 This is a private function, subject to change or removal with no
4462 deprecation.
4464 This function computes F(x), where F is the factor remaining in E_1(x)
4465 when exp(-x)/x is factored out. That is,::
4467 E_1(x) = exp(-x)/x * F(x)
4469 or
4471 F(x) = x * exp(x) * E_1(x)
4473 The function is defined for real x >= 0. For x < 0, nan is returned.
4475 F has the properties:
4477 * F(0) = 0
4478 * F(x) is increasing on [0, inf).
4479 * The limit as x goes to infinity of F(x) is 1.
4481 Parameters
4482 ----------
4483 x: array_like
4484 The input values. Must be real. The implementation is limited to
4485 double precision floating point, so other types will be cast to
4486 to double precision.
4487 out : ndarray, optional
4488 Optional output array for the function results
4490 Returns
4491 -------
4492 scalar or ndarray
4493 Values of the scaled exponential integral.
4495 See Also
4496 --------
4497 exp1 : exponential integral E_1
4499 Examples
4500 --------
4501 >>> from scipy.special import _scaled_exp1
4502 >>> _scaled_exp1([0, 0.1, 1, 10, 100])
4504 """
4505)
4508add_newdoc("exp10",
4509 """
4510 exp10(x, out=None)
4512 Compute ``10**x`` element-wise.
4514 Parameters
4515 ----------
4516 x : array_like
4517 `x` must contain real numbers.
4518 out : ndarray, optional
4519 Optional output array for the function values
4521 Returns
4522 -------
4523 scalar or ndarray
4524 ``10**x``, computed element-wise.
4526 Examples
4527 --------
4528 >>> import numpy as np
4529 >>> from scipy.special import exp10
4531 >>> exp10(3)
4532 1000.0
4533 >>> x = np.array([[-1, -0.5, 0], [0.5, 1, 1.5]])
4534 >>> exp10(x)
4535 array([[ 0.1 , 0.31622777, 1. ],
4536 [ 3.16227766, 10. , 31.6227766 ]])
4538 """)
4540add_newdoc("exp2",
4541 """
4542 exp2(x, out=None)
4544 Compute ``2**x`` element-wise.
4546 Parameters
4547 ----------
4548 x : array_like
4549 `x` must contain real numbers.
4550 out : ndarray, optional
4551 Optional output array for the function values
4553 Returns
4554 -------
4555 scalar or ndarray
4556 ``2**x``, computed element-wise.
4558 Examples
4559 --------
4560 >>> import numpy as np
4561 >>> from scipy.special import exp2
4563 >>> exp2(3)
4564 8.0
4565 >>> x = np.array([[-1, -0.5, 0], [0.5, 1, 1.5]])
4566 >>> exp2(x)
4567 array([[ 0.5 , 0.70710678, 1. ],
4568 [ 1.41421356, 2. , 2.82842712]])
4569 """)
4571add_newdoc("expi",
4572 r"""
4573 expi(x, out=None)
4575 Exponential integral Ei.
4577 For real :math:`x`, the exponential integral is defined as [1]_
4579 .. math::
4581 Ei(x) = \int_{-\infty}^x \frac{e^t}{t} dt.
4583 For :math:`x > 0` the integral is understood as a Cauchy principal
4584 value.
4586 It is extended to the complex plane by analytic continuation of
4587 the function on the interval :math:`(0, \infty)`. The complex
4588 variant has a branch cut on the negative real axis.
4590 Parameters
4591 ----------
4592 x : array_like
4593 Real or complex valued argument
4594 out : ndarray, optional
4595 Optional output array for the function results
4597 Returns
4598 -------
4599 scalar or ndarray
4600 Values of the exponential integral
4602 Notes
4603 -----
4604 The exponential integrals :math:`E_1` and :math:`Ei` satisfy the
4605 relation
4607 .. math::
4609 E_1(x) = -Ei(-x)
4611 for :math:`x > 0`.
4613 See Also
4614 --------
4615 exp1 : Exponential integral :math:`E_1`
4616 expn : Generalized exponential integral :math:`E_n`
4618 References
4619 ----------
4620 .. [1] Digital Library of Mathematical Functions, 6.2.5
4621 https://dlmf.nist.gov/6.2#E5
4623 Examples
4624 --------
4625 >>> import numpy as np
4626 >>> import scipy.special as sc
4628 It is related to `exp1`.
4630 >>> x = np.array([1, 2, 3, 4])
4631 >>> -sc.expi(-x)
4632 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4633 >>> sc.exp1(x)
4634 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4636 The complex variant has a branch cut on the negative real axis.
4638 >>> sc.expi(-1 + 1e-12j)
4639 (-0.21938393439552062+3.1415926535894254j)
4640 >>> sc.expi(-1 - 1e-12j)
4641 (-0.21938393439552062-3.1415926535894254j)
4643 As the complex variant approaches the branch cut, the real parts
4644 approach the value of the real variant.
4646 >>> sc.expi(-1)
4647 -0.21938393439552062
4649 The SciPy implementation returns the real variant for complex
4650 values on the branch cut.
4652 >>> sc.expi(complex(-1, 0.0))
4653 (-0.21938393439552062-0j)
4654 >>> sc.expi(complex(-1, -0.0))
4655 (-0.21938393439552062-0j)
4657 """)
4659add_newdoc('expit',
4660 """
4661 expit(x, out=None)
4663 Expit (a.k.a. logistic sigmoid) ufunc for ndarrays.
4665 The expit function, also known as the logistic sigmoid function, is
4666 defined as ``expit(x) = 1/(1+exp(-x))``. It is the inverse of the
4667 logit function.
4669 Parameters
4670 ----------
4671 x : ndarray
4672 The ndarray to apply expit to element-wise.
4673 out : ndarray, optional
4674 Optional output array for the function values
4676 Returns
4677 -------
4678 scalar or ndarray
4679 An ndarray of the same shape as x. Its entries
4680 are `expit` of the corresponding entry of x.
4682 See Also
4683 --------
4684 logit
4686 Notes
4687 -----
4688 As a ufunc expit takes a number of optional
4689 keyword arguments. For more information
4690 see `ufuncs <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`_
4692 .. versionadded:: 0.10.0
4694 Examples
4695 --------
4696 >>> import numpy as np
4697 >>> from scipy.special import expit, logit
4699 >>> expit([-np.inf, -1.5, 0, 1.5, np.inf])
4700 array([ 0. , 0.18242552, 0.5 , 0.81757448, 1. ])
4702 `logit` is the inverse of `expit`:
4704 >>> logit(expit([-2.5, 0, 3.1, 5.0]))
4705 array([-2.5, 0. , 3.1, 5. ])
4707 Plot expit(x) for x in [-6, 6]:
4709 >>> import matplotlib.pyplot as plt
4710 >>> x = np.linspace(-6, 6, 121)
4711 >>> y = expit(x)
4712 >>> plt.plot(x, y)
4713 >>> plt.grid()
4714 >>> plt.xlim(-6, 6)
4715 >>> plt.xlabel('x')
4716 >>> plt.title('expit(x)')
4717 >>> plt.show()
4719 """)
4721add_newdoc("expm1",
4722 """
4723 expm1(x, out=None)
4725 Compute ``exp(x) - 1``.
4727 When `x` is near zero, ``exp(x)`` is near 1, so the numerical calculation
4728 of ``exp(x) - 1`` can suffer from catastrophic loss of precision.
4729 ``expm1(x)`` is implemented to avoid the loss of precision that occurs when
4730 `x` is near zero.
4732 Parameters
4733 ----------
4734 x : array_like
4735 `x` must contain real numbers.
4736 out : ndarray, optional
4737 Optional output array for the function values
4739 Returns
4740 -------
4741 scalar or ndarray
4742 ``exp(x) - 1`` computed element-wise.
4744 Examples
4745 --------
4746 >>> import numpy as np
4747 >>> from scipy.special import expm1
4749 >>> expm1(1.0)
4750 1.7182818284590451
4751 >>> expm1([-0.2, -0.1, 0, 0.1, 0.2])
4752 array([-0.18126925, -0.09516258, 0. , 0.10517092, 0.22140276])
4754 The exact value of ``exp(7.5e-13) - 1`` is::
4756 7.5000000000028125000000007031250000001318...*10**-13.
4758 Here is what ``expm1(7.5e-13)`` gives:
4760 >>> expm1(7.5e-13)
4761 7.5000000000028135e-13
4763 Compare that to ``exp(7.5e-13) - 1``, where the subtraction results in
4764 a "catastrophic" loss of precision:
4766 >>> np.exp(7.5e-13) - 1
4767 7.5006667543675576e-13
4769 """)
4771add_newdoc("expn",
4772 r"""
4773 expn(n, x, out=None)
4775 Generalized exponential integral En.
4777 For integer :math:`n \geq 0` and real :math:`x \geq 0` the
4778 generalized exponential integral is defined as [dlmf]_
4780 .. math::
4782 E_n(x) = x^{n - 1} \int_x^\infty \frac{e^{-t}}{t^n} dt.
4784 Parameters
4785 ----------
4786 n : array_like
4787 Non-negative integers
4788 x : array_like
4789 Real argument
4790 out : ndarray, optional
4791 Optional output array for the function results
4793 Returns
4794 -------
4795 scalar or ndarray
4796 Values of the generalized exponential integral
4798 See Also
4799 --------
4800 exp1 : special case of :math:`E_n` for :math:`n = 1`
4801 expi : related to :math:`E_n` when :math:`n = 1`
4803 References
4804 ----------
4805 .. [dlmf] Digital Library of Mathematical Functions, 8.19.2
4806 https://dlmf.nist.gov/8.19#E2
4808 Examples
4809 --------
4810 >>> import numpy as np
4811 >>> import scipy.special as sc
4813 Its domain is nonnegative n and x.
4815 >>> sc.expn(-1, 1.0), sc.expn(1, -1.0)
4816 (nan, nan)
4818 It has a pole at ``x = 0`` for ``n = 1, 2``; for larger ``n`` it
4819 is equal to ``1 / (n - 1)``.
4821 >>> sc.expn([0, 1, 2, 3, 4], 0)
4822 array([ inf, inf, 1. , 0.5 , 0.33333333])
4824 For n equal to 0 it reduces to ``exp(-x) / x``.
4826 >>> x = np.array([1, 2, 3, 4])
4827 >>> sc.expn(0, x)
4828 array([0.36787944, 0.06766764, 0.01659569, 0.00457891])
4829 >>> np.exp(-x) / x
4830 array([0.36787944, 0.06766764, 0.01659569, 0.00457891])
4832 For n equal to 1 it reduces to `exp1`.
4834 >>> sc.expn(1, x)
4835 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4836 >>> sc.exp1(x)
4837 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4839 """)
4841add_newdoc("exprel",
4842 r"""
4843 exprel(x, out=None)
4845 Relative error exponential, ``(exp(x) - 1)/x``.
4847 When `x` is near zero, ``exp(x)`` is near 1, so the numerical calculation
4848 of ``exp(x) - 1`` can suffer from catastrophic loss of precision.
4849 ``exprel(x)`` is implemented to avoid the loss of precision that occurs when
4850 `x` is near zero.
4852 Parameters
4853 ----------
4854 x : ndarray
4855 Input array. `x` must contain real numbers.
4856 out : ndarray, optional
4857 Optional output array for the function values
4859 Returns
4860 -------
4861 scalar or ndarray
4862 ``(exp(x) - 1)/x``, computed element-wise.
4864 See Also
4865 --------
4866 expm1
4868 Notes
4869 -----
4870 .. versionadded:: 0.17.0
4872 Examples
4873 --------
4874 >>> import numpy as np
4875 >>> from scipy.special import exprel
4877 >>> exprel(0.01)
4878 1.0050167084168056
4879 >>> exprel([-0.25, -0.1, 0, 0.1, 0.25])
4880 array([ 0.88479687, 0.95162582, 1. , 1.05170918, 1.13610167])
4882 Compare ``exprel(5e-9)`` to the naive calculation. The exact value
4883 is ``1.00000000250000000416...``.
4885 >>> exprel(5e-9)
4886 1.0000000025
4888 >>> (np.exp(5e-9) - 1)/5e-9
4889 0.99999999392252903
4890 """)
4892add_newdoc("fdtr",
4893 r"""
4894 fdtr(dfn, dfd, x, out=None)
4896 F cumulative distribution function.
4898 Returns the value of the cumulative distribution function of the
4899 F-distribution, also known as Snedecor's F-distribution or the
4900 Fisher-Snedecor distribution.
4902 The F-distribution with parameters :math:`d_n` and :math:`d_d` is the
4903 distribution of the random variable,
4905 .. math::
4906 X = \frac{U_n/d_n}{U_d/d_d},
4908 where :math:`U_n` and :math:`U_d` are random variables distributed
4909 :math:`\chi^2`, with :math:`d_n` and :math:`d_d` degrees of freedom,
4910 respectively.
4912 Parameters
4913 ----------
4914 dfn : array_like
4915 First parameter (positive float).
4916 dfd : array_like
4917 Second parameter (positive float).
4918 x : array_like
4919 Argument (nonnegative float).
4920 out : ndarray, optional
4921 Optional output array for the function values
4923 Returns
4924 -------
4925 y : scalar or ndarray
4926 The CDF of the F-distribution with parameters `dfn` and `dfd` at `x`.
4928 See Also
4929 --------
4930 fdtrc : F distribution survival function
4931 fdtri : F distribution inverse cumulative distribution
4932 scipy.stats.f : F distribution
4934 Notes
4935 -----
4936 The regularized incomplete beta function is used, according to the
4937 formula,
4939 .. math::
4940 F(d_n, d_d; x) = I_{xd_n/(d_d + xd_n)}(d_n/2, d_d/2).
4942 Wrapper for the Cephes [1]_ routine `fdtr`. The F distribution is also
4943 available as `scipy.stats.f`. Calling `fdtr` directly can improve
4944 performance compared to the ``cdf`` method of `scipy.stats.f` (see last
4945 example below).
4947 References
4948 ----------
4949 .. [1] Cephes Mathematical Functions Library,
4950 http://www.netlib.org/cephes/
4952 Examples
4953 --------
4954 Calculate the function for ``dfn=1`` and ``dfd=2`` at ``x=1``.
4956 >>> import numpy as np
4957 >>> from scipy.special import fdtr
4958 >>> fdtr(1, 2, 1)
4959 0.5773502691896258
4961 Calculate the function at several points by providing a NumPy array for
4962 `x`.
4964 >>> x = np.array([0.5, 2., 3.])
4965 >>> fdtr(1, 2, x)
4966 array([0.4472136 , 0.70710678, 0.77459667])
4968 Plot the function for several parameter sets.
4970 >>> import matplotlib.pyplot as plt
4971 >>> dfn_parameters = [1, 5, 10, 50]
4972 >>> dfd_parameters = [1, 1, 2, 3]
4973 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
4974 >>> parameters_list = list(zip(dfn_parameters, dfd_parameters,
4975 ... linestyles))
4976 >>> x = np.linspace(0, 30, 1000)
4977 >>> fig, ax = plt.subplots()
4978 >>> for parameter_set in parameters_list:
4979 ... dfn, dfd, style = parameter_set
4980 ... fdtr_vals = fdtr(dfn, dfd, x)
4981 ... ax.plot(x, fdtr_vals, label=rf"$d_n={dfn},\, d_d={dfd}$",
4982 ... ls=style)
4983 >>> ax.legend()
4984 >>> ax.set_xlabel("$x$")
4985 >>> ax.set_title("F distribution cumulative distribution function")
4986 >>> plt.show()
4988 The F distribution is also available as `scipy.stats.f`. Using `fdtr`
4989 directly can be much faster than calling the ``cdf`` method of
4990 `scipy.stats.f`, especially for small arrays or individual values.
4991 To get the same results one must use the following parametrization:
4992 ``stats.f(dfn, dfd).cdf(x)=fdtr(dfn, dfd, x)``.
4994 >>> from scipy.stats import f
4995 >>> dfn, dfd = 1, 2
4996 >>> x = 1
4997 >>> fdtr_res = fdtr(dfn, dfd, x) # this will often be faster than below
4998 >>> f_dist_res = f(dfn, dfd).cdf(x)
4999 >>> fdtr_res == f_dist_res # test that results are equal
5000 True
5001 """)
5003add_newdoc("fdtrc",
5004 r"""
5005 fdtrc(dfn, dfd, x, out=None)
5007 F survival function.
5009 Returns the complemented F-distribution function (the integral of the
5010 density from `x` to infinity).
5012 Parameters
5013 ----------
5014 dfn : array_like
5015 First parameter (positive float).
5016 dfd : array_like
5017 Second parameter (positive float).
5018 x : array_like
5019 Argument (nonnegative float).
5020 out : ndarray, optional
5021 Optional output array for the function values
5023 Returns
5024 -------
5025 y : scalar or ndarray
5026 The complemented F-distribution function with parameters `dfn` and
5027 `dfd` at `x`.
5029 See Also
5030 --------
5031 fdtr : F distribution cumulative distribution function
5032 fdtri : F distribution inverse cumulative distribution function
5033 scipy.stats.f : F distribution
5035 Notes
5036 -----
5037 The regularized incomplete beta function is used, according to the
5038 formula,
5040 .. math::
5041 F(d_n, d_d; x) = I_{d_d/(d_d + xd_n)}(d_d/2, d_n/2).
5043 Wrapper for the Cephes [1]_ routine `fdtrc`. The F distribution is also
5044 available as `scipy.stats.f`. Calling `fdtrc` directly can improve
5045 performance compared to the ``sf`` method of `scipy.stats.f` (see last
5046 example below).
5048 References
5049 ----------
5050 .. [1] Cephes Mathematical Functions Library,
5051 http://www.netlib.org/cephes/
5053 Examples
5054 --------
5055 Calculate the function for ``dfn=1`` and ``dfd=2`` at ``x=1``.
5057 >>> import numpy as np
5058 >>> from scipy.special import fdtrc
5059 >>> fdtrc(1, 2, 1)
5060 0.42264973081037427
5062 Calculate the function at several points by providing a NumPy array for
5063 `x`.
5065 >>> x = np.array([0.5, 2., 3.])
5066 >>> fdtrc(1, 2, x)
5067 array([0.5527864 , 0.29289322, 0.22540333])
5069 Plot the function for several parameter sets.
5071 >>> import matplotlib.pyplot as plt
5072 >>> dfn_parameters = [1, 5, 10, 50]
5073 >>> dfd_parameters = [1, 1, 2, 3]
5074 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5075 >>> parameters_list = list(zip(dfn_parameters, dfd_parameters,
5076 ... linestyles))
5077 >>> x = np.linspace(0, 30, 1000)
5078 >>> fig, ax = plt.subplots()
5079 >>> for parameter_set in parameters_list:
5080 ... dfn, dfd, style = parameter_set
5081 ... fdtrc_vals = fdtrc(dfn, dfd, x)
5082 ... ax.plot(x, fdtrc_vals, label=rf"$d_n={dfn},\, d_d={dfd}$",
5083 ... ls=style)
5084 >>> ax.legend()
5085 >>> ax.set_xlabel("$x$")
5086 >>> ax.set_title("F distribution survival function")
5087 >>> plt.show()
5089 The F distribution is also available as `scipy.stats.f`. Using `fdtrc`
5090 directly can be much faster than calling the ``sf`` method of
5091 `scipy.stats.f`, especially for small arrays or individual values.
5092 To get the same results one must use the following parametrization:
5093 ``stats.f(dfn, dfd).sf(x)=fdtrc(dfn, dfd, x)``.
5095 >>> from scipy.stats import f
5096 >>> dfn, dfd = 1, 2
5097 >>> x = 1
5098 >>> fdtrc_res = fdtrc(dfn, dfd, x) # this will often be faster than below
5099 >>> f_dist_res = f(dfn, dfd).sf(x)
5100 >>> f_dist_res == fdtrc_res # test that results are equal
5101 True
5102 """)
5104add_newdoc("fdtri",
5105 r"""
5106 fdtri(dfn, dfd, p, out=None)
5108 The `p`-th quantile of the F-distribution.
5110 This function is the inverse of the F-distribution CDF, `fdtr`, returning
5111 the `x` such that `fdtr(dfn, dfd, x) = p`.
5113 Parameters
5114 ----------
5115 dfn : array_like
5116 First parameter (positive float).
5117 dfd : array_like
5118 Second parameter (positive float).
5119 p : array_like
5120 Cumulative probability, in [0, 1].
5121 out : ndarray, optional
5122 Optional output array for the function values
5124 Returns
5125 -------
5126 x : scalar or ndarray
5127 The quantile corresponding to `p`.
5129 See Also
5130 --------
5131 fdtr : F distribution cumulative distribution function
5132 fdtrc : F distribution survival function
5133 scipy.stats.f : F distribution
5135 Notes
5136 -----
5137 The computation is carried out using the relation to the inverse
5138 regularized beta function, :math:`I^{-1}_x(a, b)`. Let
5139 :math:`z = I^{-1}_p(d_d/2, d_n/2).` Then,
5141 .. math::
5142 x = \frac{d_d (1 - z)}{d_n z}.
5144 If `p` is such that :math:`x < 0.5`, the following relation is used
5145 instead for improved stability: let
5146 :math:`z' = I^{-1}_{1 - p}(d_n/2, d_d/2).` Then,
5148 .. math::
5149 x = \frac{d_d z'}{d_n (1 - z')}.
5151 Wrapper for the Cephes [1]_ routine `fdtri`.
5153 The F distribution is also available as `scipy.stats.f`. Calling
5154 `fdtri` directly can improve performance compared to the ``ppf``
5155 method of `scipy.stats.f` (see last example below).
5157 References
5158 ----------
5159 .. [1] Cephes Mathematical Functions Library,
5160 http://www.netlib.org/cephes/
5162 Examples
5163 --------
5164 `fdtri` represents the inverse of the F distribution CDF which is
5165 available as `fdtr`. Here, we calculate the CDF for ``df1=1``, ``df2=2``
5166 at ``x=3``. `fdtri` then returns ``3`` given the same values for `df1`,
5167 `df2` and the computed CDF value.
5169 >>> import numpy as np
5170 >>> from scipy.special import fdtri, fdtr
5171 >>> df1, df2 = 1, 2
5172 >>> x = 3
5173 >>> cdf_value = fdtr(df1, df2, x)
5174 >>> fdtri(df1, df2, cdf_value)
5175 3.000000000000006
5177 Calculate the function at several points by providing a NumPy array for
5178 `x`.
5180 >>> x = np.array([0.1, 0.4, 0.7])
5181 >>> fdtri(1, 2, x)
5182 array([0.02020202, 0.38095238, 1.92156863])
5184 Plot the function for several parameter sets.
5186 >>> import matplotlib.pyplot as plt
5187 >>> dfn_parameters = [50, 10, 1, 50]
5188 >>> dfd_parameters = [0.5, 1, 1, 5]
5189 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5190 >>> parameters_list = list(zip(dfn_parameters, dfd_parameters,
5191 ... linestyles))
5192 >>> x = np.linspace(0, 1, 1000)
5193 >>> fig, ax = plt.subplots()
5194 >>> for parameter_set in parameters_list:
5195 ... dfn, dfd, style = parameter_set
5196 ... fdtri_vals = fdtri(dfn, dfd, x)
5197 ... ax.plot(x, fdtri_vals, label=rf"$d_n={dfn},\, d_d={dfd}$",
5198 ... ls=style)
5199 >>> ax.legend()
5200 >>> ax.set_xlabel("$x$")
5201 >>> title = "F distribution inverse cumulative distribution function"
5202 >>> ax.set_title(title)
5203 >>> ax.set_ylim(0, 30)
5204 >>> plt.show()
5206 The F distribution is also available as `scipy.stats.f`. Using `fdtri`
5207 directly can be much faster than calling the ``ppf`` method of
5208 `scipy.stats.f`, especially for small arrays or individual values.
5209 To get the same results one must use the following parametrization:
5210 ``stats.f(dfn, dfd).ppf(x)=fdtri(dfn, dfd, x)``.
5212 >>> from scipy.stats import f
5213 >>> dfn, dfd = 1, 2
5214 >>> x = 0.7
5215 >>> fdtri_res = fdtri(dfn, dfd, x) # this will often be faster than below
5216 >>> f_dist_res = f(dfn, dfd).ppf(x)
5217 >>> f_dist_res == fdtri_res # test that results are equal
5218 True
5219 """)
5221add_newdoc("fdtridfd",
5222 """
5223 fdtridfd(dfn, p, x, out=None)
5225 Inverse to `fdtr` vs dfd
5227 Finds the F density argument dfd such that ``fdtr(dfn, dfd, x) == p``.
5229 Parameters
5230 ----------
5231 dfn : array_like
5232 First parameter (positive float).
5233 p : array_like
5234 Cumulative probability, in [0, 1].
5235 x : array_like
5236 Argument (nonnegative float).
5237 out : ndarray, optional
5238 Optional output array for the function values
5240 Returns
5241 -------
5242 dfd : scalar or ndarray
5243 `dfd` such that ``fdtr(dfn, dfd, x) == p``.
5245 See Also
5246 --------
5247 fdtr : F distribution cumulative distribution function
5248 fdtrc : F distribution survival function
5249 fdtri : F distribution quantile function
5250 scipy.stats.f : F distribution
5252 Examples
5253 --------
5254 Compute the F distribution cumulative distribution function for one
5255 parameter set.
5257 >>> from scipy.special import fdtridfd, fdtr
5258 >>> dfn, dfd, x = 10, 5, 2
5259 >>> cdf_value = fdtr(dfn, dfd, x)
5260 >>> cdf_value
5261 0.7700248806501017
5263 Verify that `fdtridfd` recovers the original value for `dfd`:
5265 >>> fdtridfd(dfn, cdf_value, x)
5266 5.0
5267 """)
5269'''
5270commented out as fdtridfn seems to have bugs and is not in functions.json
5271see: https://github.com/scipy/scipy/pull/15622#discussion_r811440983
5273add_newdoc(
5274 "fdtridfn",
5275 """
5276 fdtridfn(p, dfd, x, out=None)
5278 Inverse to `fdtr` vs dfn
5280 finds the F density argument dfn such that ``fdtr(dfn, dfd, x) == p``.
5283 Parameters
5284 ----------
5285 p : array_like
5286 Cumulative probability, in [0, 1].
5287 dfd : array_like
5288 Second parameter (positive float).
5289 x : array_like
5290 Argument (nonnegative float).
5291 out : ndarray, optional
5292 Optional output array for the function values
5294 Returns
5295 -------
5296 dfn : scalar or ndarray
5297 `dfn` such that ``fdtr(dfn, dfd, x) == p``.
5299 See Also
5300 --------
5301 fdtr, fdtrc, fdtri, fdtridfd
5304 """)
5305'''
5307add_newdoc("fresnel",
5308 r"""
5309 fresnel(z, out=None)
5311 Fresnel integrals.
5313 The Fresnel integrals are defined as
5315 .. math::
5317 S(z) &= \int_0^z \sin(\pi t^2 /2) dt \\
5318 C(z) &= \int_0^z \cos(\pi t^2 /2) dt.
5320 See [dlmf]_ for details.
5322 Parameters
5323 ----------
5324 z : array_like
5325 Real or complex valued argument
5326 out : 2-tuple of ndarrays, optional
5327 Optional output arrays for the function results
5329 Returns
5330 -------
5331 S, C : 2-tuple of scalar or ndarray
5332 Values of the Fresnel integrals
5334 See Also
5335 --------
5336 fresnel_zeros : zeros of the Fresnel integrals
5338 References
5339 ----------
5340 .. [dlmf] NIST Digital Library of Mathematical Functions
5341 https://dlmf.nist.gov/7.2#iii
5343 Examples
5344 --------
5345 >>> import numpy as np
5346 >>> import scipy.special as sc
5348 As z goes to infinity along the real axis, S and C converge to 0.5.
5350 >>> S, C = sc.fresnel([0.1, 1, 10, 100, np.inf])
5351 >>> S
5352 array([0.00052359, 0.43825915, 0.46816998, 0.4968169 , 0.5 ])
5353 >>> C
5354 array([0.09999753, 0.7798934 , 0.49989869, 0.4999999 , 0.5 ])
5356 They are related to the error function `erf`.
5358 >>> z = np.array([1, 2, 3, 4])
5359 >>> zeta = 0.5 * np.sqrt(np.pi) * (1 - 1j) * z
5360 >>> S, C = sc.fresnel(z)
5361 >>> C + 1j*S
5362 array([0.7798934 +0.43825915j, 0.48825341+0.34341568j,
5363 0.60572079+0.496313j , 0.49842603+0.42051575j])
5364 >>> 0.5 * (1 + 1j) * sc.erf(zeta)
5365 array([0.7798934 +0.43825915j, 0.48825341+0.34341568j,
5366 0.60572079+0.496313j , 0.49842603+0.42051575j])
5368 """)
5370add_newdoc("gamma",
5371 r"""
5372 gamma(z, out=None)
5374 gamma function.
5376 The gamma function is defined as
5378 .. math::
5380 \Gamma(z) = \int_0^\infty t^{z-1} e^{-t} dt
5382 for :math:`\Re(z) > 0` and is extended to the rest of the complex
5383 plane by analytic continuation. See [dlmf]_ for more details.
5385 Parameters
5386 ----------
5387 z : array_like
5388 Real or complex valued argument
5389 out : ndarray, optional
5390 Optional output array for the function values
5392 Returns
5393 -------
5394 scalar or ndarray
5395 Values of the gamma function
5397 Notes
5398 -----
5399 The gamma function is often referred to as the generalized
5400 factorial since :math:`\Gamma(n + 1) = n!` for natural numbers
5401 :math:`n`. More generally it satisfies the recurrence relation
5402 :math:`\Gamma(z + 1) = z \cdot \Gamma(z)` for complex :math:`z`,
5403 which, combined with the fact that :math:`\Gamma(1) = 1`, implies
5404 the above identity for :math:`z = n`.
5406 References
5407 ----------
5408 .. [dlmf] NIST Digital Library of Mathematical Functions
5409 https://dlmf.nist.gov/5.2#E1
5411 Examples
5412 --------
5413 >>> import numpy as np
5414 >>> from scipy.special import gamma, factorial
5416 >>> gamma([0, 0.5, 1, 5])
5417 array([ inf, 1.77245385, 1. , 24. ])
5419 >>> z = 2.5 + 1j
5420 >>> gamma(z)
5421 (0.77476210455108352+0.70763120437959293j)
5422 >>> gamma(z+1), z*gamma(z) # Recurrence property
5423 ((1.2292740569981171+2.5438401155000685j),
5424 (1.2292740569981158+2.5438401155000658j))
5426 >>> gamma(0.5)**2 # gamma(0.5) = sqrt(pi)
5427 3.1415926535897927
5429 Plot gamma(x) for real x
5431 >>> x = np.linspace(-3.5, 5.5, 2251)
5432 >>> y = gamma(x)
5434 >>> import matplotlib.pyplot as plt
5435 >>> plt.plot(x, y, 'b', alpha=0.6, label='gamma(x)')
5436 >>> k = np.arange(1, 7)
5437 >>> plt.plot(k, factorial(k-1), 'k*', alpha=0.6,
5438 ... label='(x-1)!, x = 1, 2, ...')
5439 >>> plt.xlim(-3.5, 5.5)
5440 >>> plt.ylim(-10, 25)
5441 >>> plt.grid()
5442 >>> plt.xlabel('x')
5443 >>> plt.legend(loc='lower right')
5444 >>> plt.show()
5446 """)
5448add_newdoc("gammainc",
5449 r"""
5450 gammainc(a, x, out=None)
5452 Regularized lower incomplete gamma function.
5454 It is defined as
5456 .. math::
5458 P(a, x) = \frac{1}{\Gamma(a)} \int_0^x t^{a - 1}e^{-t} dt
5460 for :math:`a > 0` and :math:`x \geq 0`. See [dlmf]_ for details.
5462 Parameters
5463 ----------
5464 a : array_like
5465 Positive parameter
5466 x : array_like
5467 Nonnegative argument
5468 out : ndarray, optional
5469 Optional output array for the function values
5471 Returns
5472 -------
5473 scalar or ndarray
5474 Values of the lower incomplete gamma function
5476 Notes
5477 -----
5478 The function satisfies the relation ``gammainc(a, x) +
5479 gammaincc(a, x) = 1`` where `gammaincc` is the regularized upper
5480 incomplete gamma function.
5482 The implementation largely follows that of [boost]_.
5484 See also
5485 --------
5486 gammaincc : regularized upper incomplete gamma function
5487 gammaincinv : inverse of the regularized lower incomplete gamma function
5488 gammainccinv : inverse of the regularized upper incomplete gamma function
5490 References
5491 ----------
5492 .. [dlmf] NIST Digital Library of Mathematical functions
5493 https://dlmf.nist.gov/8.2#E4
5494 .. [boost] Maddock et. al., "Incomplete Gamma Functions",
5495 https://www.boost.org/doc/libs/1_61_0/libs/math/doc/html/math_toolkit/sf_gamma/igamma.html
5497 Examples
5498 --------
5499 >>> import scipy.special as sc
5501 It is the CDF of the gamma distribution, so it starts at 0 and
5502 monotonically increases to 1.
5504 >>> sc.gammainc(0.5, [0, 1, 10, 100])
5505 array([0. , 0.84270079, 0.99999226, 1. ])
5507 It is equal to one minus the upper incomplete gamma function.
5509 >>> a, x = 0.5, 0.4
5510 >>> sc.gammainc(a, x)
5511 0.6289066304773024
5512 >>> 1 - sc.gammaincc(a, x)
5513 0.6289066304773024
5515 """)
5517add_newdoc("gammaincc",
5518 r"""
5519 gammaincc(a, x, out=None)
5521 Regularized upper incomplete gamma function.
5523 It is defined as
5525 .. math::
5527 Q(a, x) = \frac{1}{\Gamma(a)} \int_x^\infty t^{a - 1}e^{-t} dt
5529 for :math:`a > 0` and :math:`x \geq 0`. See [dlmf]_ for details.
5531 Parameters
5532 ----------
5533 a : array_like
5534 Positive parameter
5535 x : array_like
5536 Nonnegative argument
5537 out : ndarray, optional
5538 Optional output array for the function values
5540 Returns
5541 -------
5542 scalar or ndarray
5543 Values of the upper incomplete gamma function
5545 Notes
5546 -----
5547 The function satisfies the relation ``gammainc(a, x) +
5548 gammaincc(a, x) = 1`` where `gammainc` is the regularized lower
5549 incomplete gamma function.
5551 The implementation largely follows that of [boost]_.
5553 See also
5554 --------
5555 gammainc : regularized lower incomplete gamma function
5556 gammaincinv : inverse of the regularized lower incomplete gamma function
5557 gammainccinv : inverse of the regularized upper incomplete gamma function
5559 References
5560 ----------
5561 .. [dlmf] NIST Digital Library of Mathematical functions
5562 https://dlmf.nist.gov/8.2#E4
5563 .. [boost] Maddock et. al., "Incomplete Gamma Functions",
5564 https://www.boost.org/doc/libs/1_61_0/libs/math/doc/html/math_toolkit/sf_gamma/igamma.html
5566 Examples
5567 --------
5568 >>> import scipy.special as sc
5570 It is the survival function of the gamma distribution, so it
5571 starts at 1 and monotonically decreases to 0.
5573 >>> sc.gammaincc(0.5, [0, 1, 10, 100, 1000])
5574 array([1.00000000e+00, 1.57299207e-01, 7.74421643e-06, 2.08848758e-45,
5575 0.00000000e+00])
5577 It is equal to one minus the lower incomplete gamma function.
5579 >>> a, x = 0.5, 0.4
5580 >>> sc.gammaincc(a, x)
5581 0.37109336952269756
5582 >>> 1 - sc.gammainc(a, x)
5583 0.37109336952269756
5585 """)
5587add_newdoc("gammainccinv",
5588 """
5589 gammainccinv(a, y, out=None)
5591 Inverse of the regularized upper incomplete gamma function.
5593 Given an input :math:`y` between 0 and 1, returns :math:`x` such
5594 that :math:`y = Q(a, x)`. Here :math:`Q` is the regularized upper
5595 incomplete gamma function; see `gammaincc`. This is well-defined
5596 because the upper incomplete gamma function is monotonic as can
5597 be seen from its definition in [dlmf]_.
5599 Parameters
5600 ----------
5601 a : array_like
5602 Positive parameter
5603 y : array_like
5604 Argument between 0 and 1, inclusive
5605 out : ndarray, optional
5606 Optional output array for the function values
5608 Returns
5609 -------
5610 scalar or ndarray
5611 Values of the inverse of the upper incomplete gamma function
5613 See Also
5614 --------
5615 gammaincc : regularized upper incomplete gamma function
5616 gammainc : regularized lower incomplete gamma function
5617 gammaincinv : inverse of the regularized lower incomplete gamma function
5619 References
5620 ----------
5621 .. [dlmf] NIST Digital Library of Mathematical Functions
5622 https://dlmf.nist.gov/8.2#E4
5624 Examples
5625 --------
5626 >>> import scipy.special as sc
5628 It starts at infinity and monotonically decreases to 0.
5630 >>> sc.gammainccinv(0.5, [0, 0.1, 0.5, 1])
5631 array([ inf, 1.35277173, 0.22746821, 0. ])
5633 It inverts the upper incomplete gamma function.
5635 >>> a, x = 0.5, [0, 0.1, 0.5, 1]
5636 >>> sc.gammaincc(a, sc.gammainccinv(a, x))
5637 array([0. , 0.1, 0.5, 1. ])
5639 >>> a, x = 0.5, [0, 10, 50]
5640 >>> sc.gammainccinv(a, sc.gammaincc(a, x))
5641 array([ 0., 10., 50.])
5643 """)
5645add_newdoc("gammaincinv",
5646 """
5647 gammaincinv(a, y, out=None)
5649 Inverse to the regularized lower incomplete gamma function.
5651 Given an input :math:`y` between 0 and 1, returns :math:`x` such
5652 that :math:`y = P(a, x)`. Here :math:`P` is the regularized lower
5653 incomplete gamma function; see `gammainc`. This is well-defined
5654 because the lower incomplete gamma function is monotonic as can be
5655 seen from its definition in [dlmf]_.
5657 Parameters
5658 ----------
5659 a : array_like
5660 Positive parameter
5661 y : array_like
5662 Parameter between 0 and 1, inclusive
5663 out : ndarray, optional
5664 Optional output array for the function values
5666 Returns
5667 -------
5668 scalar or ndarray
5669 Values of the inverse of the lower incomplete gamma function
5671 See Also
5672 --------
5673 gammainc : regularized lower incomplete gamma function
5674 gammaincc : regularized upper incomplete gamma function
5675 gammainccinv : inverse of the regularized upper incomplete gamma function
5677 References
5678 ----------
5679 .. [dlmf] NIST Digital Library of Mathematical Functions
5680 https://dlmf.nist.gov/8.2#E4
5682 Examples
5683 --------
5684 >>> import scipy.special as sc
5686 It starts at 0 and monotonically increases to infinity.
5688 >>> sc.gammaincinv(0.5, [0, 0.1 ,0.5, 1])
5689 array([0. , 0.00789539, 0.22746821, inf])
5691 It inverts the lower incomplete gamma function.
5693 >>> a, x = 0.5, [0, 0.1, 0.5, 1]
5694 >>> sc.gammainc(a, sc.gammaincinv(a, x))
5695 array([0. , 0.1, 0.5, 1. ])
5697 >>> a, x = 0.5, [0, 10, 25]
5698 >>> sc.gammaincinv(a, sc.gammainc(a, x))
5699 array([ 0. , 10. , 25.00001465])
5701 """)
5703add_newdoc("gammaln",
5704 r"""
5705 gammaln(x, out=None)
5707 Logarithm of the absolute value of the gamma function.
5709 Defined as
5711 .. math::
5713 \ln(\lvert\Gamma(x)\rvert)
5715 where :math:`\Gamma` is the gamma function. For more details on
5716 the gamma function, see [dlmf]_.
5718 Parameters
5719 ----------
5720 x : array_like
5721 Real argument
5722 out : ndarray, optional
5723 Optional output array for the function results
5725 Returns
5726 -------
5727 scalar or ndarray
5728 Values of the log of the absolute value of gamma
5730 See Also
5731 --------
5732 gammasgn : sign of the gamma function
5733 loggamma : principal branch of the logarithm of the gamma function
5735 Notes
5736 -----
5737 It is the same function as the Python standard library function
5738 :func:`math.lgamma`.
5740 When used in conjunction with `gammasgn`, this function is useful
5741 for working in logspace on the real axis without having to deal
5742 with complex numbers via the relation ``exp(gammaln(x)) =
5743 gammasgn(x) * gamma(x)``.
5745 For complex-valued log-gamma, use `loggamma` instead of `gammaln`.
5747 References
5748 ----------
5749 .. [dlmf] NIST Digital Library of Mathematical Functions
5750 https://dlmf.nist.gov/5
5752 Examples
5753 --------
5754 >>> import numpy as np
5755 >>> import scipy.special as sc
5757 It has two positive zeros.
5759 >>> sc.gammaln([1, 2])
5760 array([0., 0.])
5762 It has poles at nonpositive integers.
5764 >>> sc.gammaln([0, -1, -2, -3, -4])
5765 array([inf, inf, inf, inf, inf])
5767 It asymptotically approaches ``x * log(x)`` (Stirling's formula).
5769 >>> x = np.array([1e10, 1e20, 1e40, 1e80])
5770 >>> sc.gammaln(x)
5771 array([2.20258509e+11, 4.50517019e+21, 9.11034037e+41, 1.83206807e+82])
5772 >>> x * np.log(x)
5773 array([2.30258509e+11, 4.60517019e+21, 9.21034037e+41, 1.84206807e+82])
5775 """)
5777add_newdoc("gammasgn",
5778 r"""
5779 gammasgn(x, out=None)
5781 Sign of the gamma function.
5783 It is defined as
5785 .. math::
5787 \text{gammasgn}(x) =
5788 \begin{cases}
5789 +1 & \Gamma(x) > 0 \\
5790 -1 & \Gamma(x) < 0
5791 \end{cases}
5793 where :math:`\Gamma` is the gamma function; see `gamma`. This
5794 definition is complete since the gamma function is never zero;
5795 see the discussion after [dlmf]_.
5797 Parameters
5798 ----------
5799 x : array_like
5800 Real argument
5801 out : ndarray, optional
5802 Optional output array for the function values
5804 Returns
5805 -------
5806 scalar or ndarray
5807 Sign of the gamma function
5809 Notes
5810 -----
5811 The gamma function can be computed as ``gammasgn(x) *
5812 np.exp(gammaln(x))``.
5814 See Also
5815 --------
5816 gamma : the gamma function
5817 gammaln : log of the absolute value of the gamma function
5818 loggamma : analytic continuation of the log of the gamma function
5820 References
5821 ----------
5822 .. [dlmf] NIST Digital Library of Mathematical Functions
5823 https://dlmf.nist.gov/5.2#E1
5825 Examples
5826 --------
5827 >>> import numpy as np
5828 >>> import scipy.special as sc
5830 It is 1 for `x > 0`.
5832 >>> sc.gammasgn([1, 2, 3, 4])
5833 array([1., 1., 1., 1.])
5835 It alternates between -1 and 1 for negative integers.
5837 >>> sc.gammasgn([-0.5, -1.5, -2.5, -3.5])
5838 array([-1., 1., -1., 1.])
5840 It can be used to compute the gamma function.
5842 >>> x = [1.5, 0.5, -0.5, -1.5]
5843 >>> sc.gammasgn(x) * np.exp(sc.gammaln(x))
5844 array([ 0.88622693, 1.77245385, -3.5449077 , 2.3632718 ])
5845 >>> sc.gamma(x)
5846 array([ 0.88622693, 1.77245385, -3.5449077 , 2.3632718 ])
5848 """)
5850add_newdoc("gdtr",
5851 r"""
5852 gdtr(a, b, x, out=None)
5854 Gamma distribution cumulative distribution function.
5856 Returns the integral from zero to `x` of the gamma probability density
5857 function,
5859 .. math::
5861 F = \int_0^x \frac{a^b}{\Gamma(b)} t^{b-1} e^{-at}\,dt,
5863 where :math:`\Gamma` is the gamma function.
5865 Parameters
5866 ----------
5867 a : array_like
5868 The rate parameter of the gamma distribution, sometimes denoted
5869 :math:`\beta` (float). It is also the reciprocal of the scale
5870 parameter :math:`\theta`.
5871 b : array_like
5872 The shape parameter of the gamma distribution, sometimes denoted
5873 :math:`\alpha` (float).
5874 x : array_like
5875 The quantile (upper limit of integration; float).
5876 out : ndarray, optional
5877 Optional output array for the function values
5879 See also
5880 --------
5881 gdtrc : 1 - CDF of the gamma distribution.
5882 scipy.stats.gamma: Gamma distribution
5884 Returns
5885 -------
5886 F : scalar or ndarray
5887 The CDF of the gamma distribution with parameters `a` and `b`
5888 evaluated at `x`.
5890 Notes
5891 -----
5892 The evaluation is carried out using the relation to the incomplete gamma
5893 integral (regularized gamma function).
5895 Wrapper for the Cephes [1]_ routine `gdtr`. Calling `gdtr` directly can
5896 improve performance compared to the ``cdf`` method of `scipy.stats.gamma`
5897 (see last example below).
5899 References
5900 ----------
5901 .. [1] Cephes Mathematical Functions Library,
5902 http://www.netlib.org/cephes/
5904 Examples
5905 --------
5906 Compute the function for ``a=1``, ``b=2`` at ``x=5``.
5908 >>> import numpy as np
5909 >>> from scipy.special import gdtr
5910 >>> import matplotlib.pyplot as plt
5911 >>> gdtr(1., 2., 5.)
5912 0.9595723180054873
5914 Compute the function for ``a=1`` and ``b=2`` at several points by
5915 providing a NumPy array for `x`.
5917 >>> xvalues = np.array([1., 2., 3., 4])
5918 >>> gdtr(1., 1., xvalues)
5919 array([0.63212056, 0.86466472, 0.95021293, 0.98168436])
5921 `gdtr` can evaluate different parameter sets by providing arrays with
5922 broadcasting compatible shapes for `a`, `b` and `x`. Here we compute the
5923 function for three different `a` at four positions `x` and ``b=3``,
5924 resulting in a 3x4 array.
5926 >>> a = np.array([[0.5], [1.5], [2.5]])
5927 >>> x = np.array([1., 2., 3., 4])
5928 >>> a.shape, x.shape
5929 ((3, 1), (4,))
5931 >>> gdtr(a, 3., x)
5932 array([[0.01438768, 0.0803014 , 0.19115317, 0.32332358],
5933 [0.19115317, 0.57680992, 0.82642193, 0.9380312 ],
5934 [0.45618688, 0.87534798, 0.97974328, 0.9972306 ]])
5936 Plot the function for four different parameter sets.
5938 >>> a_parameters = [0.3, 1, 2, 6]
5939 >>> b_parameters = [2, 10, 15, 20]
5940 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5941 >>> parameters_list = list(zip(a_parameters, b_parameters, linestyles))
5942 >>> x = np.linspace(0, 30, 1000)
5943 >>> fig, ax = plt.subplots()
5944 >>> for parameter_set in parameters_list:
5945 ... a, b, style = parameter_set
5946 ... gdtr_vals = gdtr(a, b, x)
5947 ... ax.plot(x, gdtr_vals, label=f"$a= {a},\, b={b}$", ls=style)
5948 >>> ax.legend()
5949 >>> ax.set_xlabel("$x$")
5950 >>> ax.set_title("Gamma distribution cumulative distribution function")
5951 >>> plt.show()
5953 The gamma distribution is also available as `scipy.stats.gamma`. Using
5954 `gdtr` directly can be much faster than calling the ``cdf`` method of
5955 `scipy.stats.gamma`, especially for small arrays or individual values.
5956 To get the same results one must use the following parametrization:
5957 ``stats.gamma(b, scale=1/a).cdf(x)=gdtr(a, b, x)``.
5959 >>> from scipy.stats import gamma
5960 >>> a = 2.
5961 >>> b = 3
5962 >>> x = 1.
5963 >>> gdtr_result = gdtr(a, b, x) # this will often be faster than below
5964 >>> gamma_dist_result = gamma(b, scale=1/a).cdf(x)
5965 >>> gdtr_result == gamma_dist_result # test that results are equal
5966 True
5967 """)
5969add_newdoc("gdtrc",
5970 r"""
5971 gdtrc(a, b, x, out=None)
5973 Gamma distribution survival function.
5975 Integral from `x` to infinity of the gamma probability density function,
5977 .. math::
5979 F = \int_x^\infty \frac{a^b}{\Gamma(b)} t^{b-1} e^{-at}\,dt,
5981 where :math:`\Gamma` is the gamma function.
5983 Parameters
5984 ----------
5985 a : array_like
5986 The rate parameter of the gamma distribution, sometimes denoted
5987 :math:`\beta` (float). It is also the reciprocal of the scale
5988 parameter :math:`\theta`.
5989 b : array_like
5990 The shape parameter of the gamma distribution, sometimes denoted
5991 :math:`\alpha` (float).
5992 x : array_like
5993 The quantile (lower limit of integration; float).
5994 out : ndarray, optional
5995 Optional output array for the function values
5997 Returns
5998 -------
5999 F : scalar or ndarray
6000 The survival function of the gamma distribution with parameters `a`
6001 and `b` evaluated at `x`.
6003 See Also
6004 --------
6005 gdtr: Gamma distribution cumulative distribution function
6006 scipy.stats.gamma: Gamma distribution
6007 gdtrix
6009 Notes
6010 -----
6011 The evaluation is carried out using the relation to the incomplete gamma
6012 integral (regularized gamma function).
6014 Wrapper for the Cephes [1]_ routine `gdtrc`. Calling `gdtrc` directly can
6015 improve performance compared to the ``sf`` method of `scipy.stats.gamma`
6016 (see last example below).
6018 References
6019 ----------
6020 .. [1] Cephes Mathematical Functions Library,
6021 http://www.netlib.org/cephes/
6023 Examples
6024 --------
6025 Compute the function for ``a=1`` and ``b=2`` at ``x=5``.
6027 >>> import numpy as np
6028 >>> from scipy.special import gdtrc
6029 >>> import matplotlib.pyplot as plt
6030 >>> gdtrc(1., 2., 5.)
6031 0.04042768199451279
6033 Compute the function for ``a=1``, ``b=2`` at several points by providing
6034 a NumPy array for `x`.
6036 >>> xvalues = np.array([1., 2., 3., 4])
6037 >>> gdtrc(1., 1., xvalues)
6038 array([0.36787944, 0.13533528, 0.04978707, 0.01831564])
6040 `gdtrc` can evaluate different parameter sets by providing arrays with
6041 broadcasting compatible shapes for `a`, `b` and `x`. Here we compute the
6042 function for three different `a` at four positions `x` and ``b=3``,
6043 resulting in a 3x4 array.
6045 >>> a = np.array([[0.5], [1.5], [2.5]])
6046 >>> x = np.array([1., 2., 3., 4])
6047 >>> a.shape, x.shape
6048 ((3, 1), (4,))
6050 >>> gdtrc(a, 3., x)
6051 array([[0.98561232, 0.9196986 , 0.80884683, 0.67667642],
6052 [0.80884683, 0.42319008, 0.17357807, 0.0619688 ],
6053 [0.54381312, 0.12465202, 0.02025672, 0.0027694 ]])
6055 Plot the function for four different parameter sets.
6057 >>> a_parameters = [0.3, 1, 2, 6]
6058 >>> b_parameters = [2, 10, 15, 20]
6059 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
6060 >>> parameters_list = list(zip(a_parameters, b_parameters, linestyles))
6061 >>> x = np.linspace(0, 30, 1000)
6062 >>> fig, ax = plt.subplots()
6063 >>> for parameter_set in parameters_list:
6064 ... a, b, style = parameter_set
6065 ... gdtrc_vals = gdtrc(a, b, x)
6066 ... ax.plot(x, gdtrc_vals, label=f"$a= {a},\, b={b}$", ls=style)
6067 >>> ax.legend()
6068 >>> ax.set_xlabel("$x$")
6069 >>> ax.set_title("Gamma distribution survival function")
6070 >>> plt.show()
6072 The gamma distribution is also available as `scipy.stats.gamma`.
6073 Using `gdtrc` directly can be much faster than calling the ``sf`` method
6074 of `scipy.stats.gamma`, especially for small arrays or individual
6075 values. To get the same results one must use the following parametrization:
6076 ``stats.gamma(b, scale=1/a).sf(x)=gdtrc(a, b, x)``.
6078 >>> from scipy.stats import gamma
6079 >>> a = 2
6080 >>> b = 3
6081 >>> x = 1.
6082 >>> gdtrc_result = gdtrc(a, b, x) # this will often be faster than below
6083 >>> gamma_dist_result = gamma(b, scale=1/a).sf(x)
6084 >>> gdtrc_result == gamma_dist_result # test that results are equal
6085 True
6086 """)
6088add_newdoc("gdtria",
6089 """
6090 gdtria(p, b, x, out=None)
6092 Inverse of `gdtr` vs a.
6094 Returns the inverse with respect to the parameter `a` of ``p =
6095 gdtr(a, b, x)``, the cumulative distribution function of the gamma
6096 distribution.
6098 Parameters
6099 ----------
6100 p : array_like
6101 Probability values.
6102 b : array_like
6103 `b` parameter values of `gdtr(a, b, x)`. `b` is the "shape" parameter
6104 of the gamma distribution.
6105 x : array_like
6106 Nonnegative real values, from the domain of the gamma distribution.
6107 out : ndarray, optional
6108 If a fourth argument is given, it must be a numpy.ndarray whose size
6109 matches the broadcast result of `a`, `b` and `x`. `out` is then the
6110 array returned by the function.
6112 Returns
6113 -------
6114 a : scalar or ndarray
6115 Values of the `a` parameter such that `p = gdtr(a, b, x)`. `1/a`
6116 is the "scale" parameter of the gamma distribution.
6118 See Also
6119 --------
6120 gdtr : CDF of the gamma distribution.
6121 gdtrib : Inverse with respect to `b` of `gdtr(a, b, x)`.
6122 gdtrix : Inverse with respect to `x` of `gdtr(a, b, x)`.
6124 Notes
6125 -----
6126 Wrapper for the CDFLIB [1]_ Fortran routine `cdfgam`.
6128 The cumulative distribution function `p` is computed using a routine by
6129 DiDinato and Morris [2]_. Computation of `a` involves a search for a value
6130 that produces the desired value of `p`. The search relies on the
6131 monotonicity of `p` with `a`.
6133 References
6134 ----------
6135 .. [1] Barry Brown, James Lovato, and Kathy Russell,
6136 CDFLIB: Library of Fortran Routines for Cumulative Distribution
6137 Functions, Inverses, and Other Parameters.
6138 .. [2] DiDinato, A. R. and Morris, A. H.,
6139 Computation of the incomplete gamma function ratios and their
6140 inverse. ACM Trans. Math. Softw. 12 (1986), 377-393.
6142 Examples
6143 --------
6144 First evaluate `gdtr`.
6146 >>> from scipy.special import gdtr, gdtria
6147 >>> p = gdtr(1.2, 3.4, 5.6)
6148 >>> print(p)
6149 0.94378087442
6151 Verify the inverse.
6153 >>> gdtria(p, 3.4, 5.6)
6154 1.2
6155 """)
6157add_newdoc("gdtrib",
6158 """
6159 gdtrib(a, p, x, out=None)
6161 Inverse of `gdtr` vs b.
6163 Returns the inverse with respect to the parameter `b` of ``p =
6164 gdtr(a, b, x)``, the cumulative distribution function of the gamma
6165 distribution.
6167 Parameters
6168 ----------
6169 a : array_like
6170 `a` parameter values of `gdtr(a, b, x)`. `1/a` is the "scale"
6171 parameter of the gamma distribution.
6172 p : array_like
6173 Probability values.
6174 x : array_like
6175 Nonnegative real values, from the domain of the gamma distribution.
6176 out : ndarray, optional
6177 If a fourth argument is given, it must be a numpy.ndarray whose size
6178 matches the broadcast result of `a`, `b` and `x`. `out` is then the
6179 array returned by the function.
6181 Returns
6182 -------
6183 b : scalar or ndarray
6184 Values of the `b` parameter such that `p = gdtr(a, b, x)`. `b` is
6185 the "shape" parameter of the gamma distribution.
6187 See Also
6188 --------
6189 gdtr : CDF of the gamma distribution.
6190 gdtria : Inverse with respect to `a` of `gdtr(a, b, x)`.
6191 gdtrix : Inverse with respect to `x` of `gdtr(a, b, x)`.
6193 Notes
6194 -----
6195 Wrapper for the CDFLIB [1]_ Fortran routine `cdfgam`.
6197 The cumulative distribution function `p` is computed using a routine by
6198 DiDinato and Morris [2]_. Computation of `b` involves a search for a value
6199 that produces the desired value of `p`. The search relies on the
6200 monotonicity of `p` with `b`.
6202 References
6203 ----------
6204 .. [1] Barry Brown, James Lovato, and Kathy Russell,
6205 CDFLIB: Library of Fortran Routines for Cumulative Distribution
6206 Functions, Inverses, and Other Parameters.
6207 .. [2] DiDinato, A. R. and Morris, A. H.,
6208 Computation of the incomplete gamma function ratios and their
6209 inverse. ACM Trans. Math. Softw. 12 (1986), 377-393.
6211 Examples
6212 --------
6213 First evaluate `gdtr`.
6215 >>> from scipy.special import gdtr, gdtrib
6216 >>> p = gdtr(1.2, 3.4, 5.6)
6217 >>> print(p)
6218 0.94378087442
6220 Verify the inverse.
6222 >>> gdtrib(1.2, p, 5.6)
6223 3.3999999999723882
6224 """)
6226add_newdoc("gdtrix",
6227 """
6228 gdtrix(a, b, p, out=None)
6230 Inverse of `gdtr` vs x.
6232 Returns the inverse with respect to the parameter `x` of ``p =
6233 gdtr(a, b, x)``, the cumulative distribution function of the gamma
6234 distribution. This is also known as the pth quantile of the
6235 distribution.
6237 Parameters
6238 ----------
6239 a : array_like
6240 `a` parameter values of `gdtr(a, b, x)`. `1/a` is the "scale"
6241 parameter of the gamma distribution.
6242 b : array_like
6243 `b` parameter values of `gdtr(a, b, x)`. `b` is the "shape" parameter
6244 of the gamma distribution.
6245 p : array_like
6246 Probability values.
6247 out : ndarray, optional
6248 If a fourth argument is given, it must be a numpy.ndarray whose size
6249 matches the broadcast result of `a`, `b` and `x`. `out` is then the
6250 array returned by the function.
6252 Returns
6253 -------
6254 x : scalar or ndarray
6255 Values of the `x` parameter such that `p = gdtr(a, b, x)`.
6257 See Also
6258 --------
6259 gdtr : CDF of the gamma distribution.
6260 gdtria : Inverse with respect to `a` of `gdtr(a, b, x)`.
6261 gdtrib : Inverse with respect to `b` of `gdtr(a, b, x)`.
6263 Notes
6264 -----
6265 Wrapper for the CDFLIB [1]_ Fortran routine `cdfgam`.
6267 The cumulative distribution function `p` is computed using a routine by
6268 DiDinato and Morris [2]_. Computation of `x` involves a search for a value
6269 that produces the desired value of `p`. The search relies on the
6270 monotonicity of `p` with `x`.
6272 References
6273 ----------
6274 .. [1] Barry Brown, James Lovato, and Kathy Russell,
6275 CDFLIB: Library of Fortran Routines for Cumulative Distribution
6276 Functions, Inverses, and Other Parameters.
6277 .. [2] DiDinato, A. R. and Morris, A. H.,
6278 Computation of the incomplete gamma function ratios and their
6279 inverse. ACM Trans. Math. Softw. 12 (1986), 377-393.
6281 Examples
6282 --------
6283 First evaluate `gdtr`.
6285 >>> from scipy.special import gdtr, gdtrix
6286 >>> p = gdtr(1.2, 3.4, 5.6)
6287 >>> print(p)
6288 0.94378087442
6290 Verify the inverse.
6292 >>> gdtrix(1.2, 3.4, p)
6293 5.5999999999999996
6294 """)
6296add_newdoc("hankel1",
6297 r"""
6298 hankel1(v, z, out=None)
6300 Hankel function of the first kind
6302 Parameters
6303 ----------
6304 v : array_like
6305 Order (float).
6306 z : array_like
6307 Argument (float or complex).
6308 out : ndarray, optional
6309 Optional output array for the function values
6311 Returns
6312 -------
6313 scalar or ndarray
6314 Values of the Hankel function of the first kind.
6316 Notes
6317 -----
6318 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6319 computation using the relation,
6321 .. math:: H^{(1)}_v(z) = \frac{2}{\imath\pi} \exp(-\imath \pi v/2) K_v(z \exp(-\imath\pi/2))
6323 where :math:`K_v` is the modified Bessel function of the second kind.
6324 For negative orders, the relation
6326 .. math:: H^{(1)}_{-v}(z) = H^{(1)}_v(z) \exp(\imath\pi v)
6328 is used.
6330 See also
6331 --------
6332 hankel1e : ndarray
6333 This function with leading exponential behavior stripped off.
6335 References
6336 ----------
6337 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6338 of a Complex Argument and Nonnegative Order",
6339 http://netlib.org/amos/
6340 """)
6342add_newdoc("hankel1e",
6343 r"""
6344 hankel1e(v, z, out=None)
6346 Exponentially scaled Hankel function of the first kind
6348 Defined as::
6350 hankel1e(v, z) = hankel1(v, z) * exp(-1j * z)
6352 Parameters
6353 ----------
6354 v : array_like
6355 Order (float).
6356 z : array_like
6357 Argument (float or complex).
6358 out : ndarray, optional
6359 Optional output array for the function values
6361 Returns
6362 -------
6363 scalar or ndarray
6364 Values of the exponentially scaled Hankel function.
6366 Notes
6367 -----
6368 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6369 computation using the relation,
6371 .. math:: H^{(1)}_v(z) = \frac{2}{\imath\pi} \exp(-\imath \pi v/2) K_v(z \exp(-\imath\pi/2))
6373 where :math:`K_v` is the modified Bessel function of the second kind.
6374 For negative orders, the relation
6376 .. math:: H^{(1)}_{-v}(z) = H^{(1)}_v(z) \exp(\imath\pi v)
6378 is used.
6380 References
6381 ----------
6382 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6383 of a Complex Argument and Nonnegative Order",
6384 http://netlib.org/amos/
6385 """)
6387add_newdoc("hankel2",
6388 r"""
6389 hankel2(v, z, out=None)
6391 Hankel function of the second kind
6393 Parameters
6394 ----------
6395 v : array_like
6396 Order (float).
6397 z : array_like
6398 Argument (float or complex).
6399 out : ndarray, optional
6400 Optional output array for the function values
6402 Returns
6403 -------
6404 scalar or ndarray
6405 Values of the Hankel function of the second kind.
6407 Notes
6408 -----
6409 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6410 computation using the relation,
6412 .. math:: H^{(2)}_v(z) = -\frac{2}{\imath\pi} \exp(\imath \pi v/2) K_v(z \exp(\imath\pi/2))
6414 where :math:`K_v` is the modified Bessel function of the second kind.
6415 For negative orders, the relation
6417 .. math:: H^{(2)}_{-v}(z) = H^{(2)}_v(z) \exp(-\imath\pi v)
6419 is used.
6421 See also
6422 --------
6423 hankel2e : this function with leading exponential behavior stripped off.
6425 References
6426 ----------
6427 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6428 of a Complex Argument and Nonnegative Order",
6429 http://netlib.org/amos/
6430 """)
6432add_newdoc("hankel2e",
6433 r"""
6434 hankel2e(v, z, out=None)
6436 Exponentially scaled Hankel function of the second kind
6438 Defined as::
6440 hankel2e(v, z) = hankel2(v, z) * exp(1j * z)
6442 Parameters
6443 ----------
6444 v : array_like
6445 Order (float).
6446 z : array_like
6447 Argument (float or complex).
6448 out : ndarray, optional
6449 Optional output array for the function values
6451 Returns
6452 -------
6453 scalar or ndarray
6454 Values of the exponentially scaled Hankel function of the second kind.
6456 Notes
6457 -----
6458 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6459 computation using the relation,
6461 .. math:: H^{(2)}_v(z) = -\frac{2}{\imath\pi} \exp(\frac{\imath \pi v}{2}) K_v(z exp(\frac{\imath\pi}{2}))
6463 where :math:`K_v` is the modified Bessel function of the second kind.
6464 For negative orders, the relation
6466 .. math:: H^{(2)}_{-v}(z) = H^{(2)}_v(z) \exp(-\imath\pi v)
6468 is used.
6470 References
6471 ----------
6472 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6473 of a Complex Argument and Nonnegative Order",
6474 http://netlib.org/amos/
6476 """)
6478add_newdoc("huber",
6479 r"""
6480 huber(delta, r, out=None)
6482 Huber loss function.
6484 .. math:: \text{huber}(\delta, r) = \begin{cases} \infty & \delta < 0 \\ \frac{1}{2}r^2 & 0 \le \delta, | r | \le \delta \\ \delta ( |r| - \frac{1}{2}\delta ) & \text{otherwise} \end{cases}
6486 Parameters
6487 ----------
6488 delta : ndarray
6489 Input array, indicating the quadratic vs. linear loss changepoint.
6490 r : ndarray
6491 Input array, possibly representing residuals.
6492 out : ndarray, optional
6493 Optional output array for the function values
6495 Returns
6496 -------
6497 scalar or ndarray
6498 The computed Huber loss function values.
6500 See also
6501 --------
6502 pseudo_huber : smooth approximation of this function
6504 Notes
6505 -----
6506 `huber` is useful as a loss function in robust statistics or machine
6507 learning to reduce the influence of outliers as compared to the common
6508 squared error loss, residuals with a magnitude higher than `delta` are
6509 not squared [1]_.
6511 Typically, `r` represents residuals, the difference
6512 between a model prediction and data. Then, for :math:`|r|\leq\delta`,
6513 `huber` resembles the squared error and for :math:`|r|>\delta` the
6514 absolute error. This way, the Huber loss often achieves
6515 a fast convergence in model fitting for small residuals like the squared
6516 error loss function and still reduces the influence of outliers
6517 (:math:`|r|>\delta`) like the absolute error loss. As :math:`\delta` is
6518 the cutoff between squared and absolute error regimes, it has
6519 to be tuned carefully for each problem. `huber` is also
6520 convex, making it suitable for gradient based optimization.
6522 .. versionadded:: 0.15.0
6524 References
6525 ----------
6526 .. [1] Peter Huber. "Robust Estimation of a Location Parameter",
6527 1964. Annals of Statistics. 53 (1): 73 - 101.
6529 Examples
6530 --------
6531 Import all necessary modules.
6533 >>> import numpy as np
6534 >>> from scipy.special import huber
6535 >>> import matplotlib.pyplot as plt
6537 Compute the function for ``delta=1`` at ``r=2``
6539 >>> huber(1., 2.)
6540 1.5
6542 Compute the function for different `delta` by providing a NumPy array or
6543 list for `delta`.
6545 >>> huber([1., 3., 5.], 4.)
6546 array([3.5, 7.5, 8. ])
6548 Compute the function at different points by providing a NumPy array or
6549 list for `r`.
6551 >>> huber(2., np.array([1., 1.5, 3.]))
6552 array([0.5 , 1.125, 4. ])
6554 The function can be calculated for different `delta` and `r` by
6555 providing arrays for both with compatible shapes for broadcasting.
6557 >>> r = np.array([1., 2.5, 8., 10.])
6558 >>> deltas = np.array([[1.], [5.], [9.]])
6559 >>> print(r.shape, deltas.shape)
6560 (4,) (3, 1)
6562 >>> huber(deltas, r)
6563 array([[ 0.5 , 2. , 7.5 , 9.5 ],
6564 [ 0.5 , 3.125, 27.5 , 37.5 ],
6565 [ 0.5 , 3.125, 32. , 49.5 ]])
6567 Plot the function for different `delta`.
6569 >>> x = np.linspace(-4, 4, 500)
6570 >>> deltas = [1, 2, 3]
6571 >>> linestyles = ["dashed", "dotted", "dashdot"]
6572 >>> fig, ax = plt.subplots()
6573 >>> combined_plot_parameters = list(zip(deltas, linestyles))
6574 >>> for delta, style in combined_plot_parameters:
6575 ... ax.plot(x, huber(delta, x), label=f"$\delta={delta}$", ls=style)
6576 >>> ax.legend(loc="upper center")
6577 >>> ax.set_xlabel("$x$")
6578 >>> ax.set_title("Huber loss function $h_{\delta}(x)$")
6579 >>> ax.set_xlim(-4, 4)
6580 >>> ax.set_ylim(0, 8)
6581 >>> plt.show()
6582 """)
6584add_newdoc("hyp0f1",
6585 r"""
6586 hyp0f1(v, z, out=None)
6588 Confluent hypergeometric limit function 0F1.
6590 Parameters
6591 ----------
6592 v : array_like
6593 Real-valued parameter
6594 z : array_like
6595 Real- or complex-valued argument
6596 out : ndarray, optional
6597 Optional output array for the function results
6599 Returns
6600 -------
6601 scalar or ndarray
6602 The confluent hypergeometric limit function
6604 Notes
6605 -----
6606 This function is defined as:
6608 .. math:: _0F_1(v, z) = \sum_{k=0}^{\infty}\frac{z^k}{(v)_k k!}.
6610 It's also the limit as :math:`q \to \infty` of :math:`_1F_1(q; v; z/q)`,
6611 and satisfies the differential equation :math:`f''(z) + vf'(z) =
6612 f(z)`. See [1]_ for more information.
6614 References
6615 ----------
6616 .. [1] Wolfram MathWorld, "Confluent Hypergeometric Limit Function",
6617 http://mathworld.wolfram.com/ConfluentHypergeometricLimitFunction.html
6619 Examples
6620 --------
6621 >>> import numpy as np
6622 >>> import scipy.special as sc
6624 It is one when `z` is zero.
6626 >>> sc.hyp0f1(1, 0)
6627 1.0
6629 It is the limit of the confluent hypergeometric function as `q`
6630 goes to infinity.
6632 >>> q = np.array([1, 10, 100, 1000])
6633 >>> v = 1
6634 >>> z = 1
6635 >>> sc.hyp1f1(q, v, z / q)
6636 array([2.71828183, 2.31481985, 2.28303778, 2.27992985])
6637 >>> sc.hyp0f1(v, z)
6638 2.2795853023360673
6640 It is related to Bessel functions.
6642 >>> n = 1
6643 >>> x = np.linspace(0, 1, 5)
6644 >>> sc.jv(n, x)
6645 array([0. , 0.12402598, 0.24226846, 0.3492436 , 0.44005059])
6646 >>> (0.5 * x)**n / sc.factorial(n) * sc.hyp0f1(n + 1, -0.25 * x**2)
6647 array([0. , 0.12402598, 0.24226846, 0.3492436 , 0.44005059])
6649 """)
6651add_newdoc("hyp1f1",
6652 r"""
6653 hyp1f1(a, b, x, out=None)
6655 Confluent hypergeometric function 1F1.
6657 The confluent hypergeometric function is defined by the series
6659 .. math::
6661 {}_1F_1(a; b; x) = \sum_{k = 0}^\infty \frac{(a)_k}{(b)_k k!} x^k.
6663 See [dlmf]_ for more details. Here :math:`(\cdot)_k` is the
6664 Pochhammer symbol; see `poch`.
6666 Parameters
6667 ----------
6668 a, b : array_like
6669 Real parameters
6670 x : array_like
6671 Real or complex argument
6672 out : ndarray, optional
6673 Optional output array for the function results
6675 Returns
6676 -------
6677 scalar or ndarray
6678 Values of the confluent hypergeometric function
6680 See also
6681 --------
6682 hyperu : another confluent hypergeometric function
6683 hyp0f1 : confluent hypergeometric limit function
6684 hyp2f1 : Gaussian hypergeometric function
6686 References
6687 ----------
6688 .. [dlmf] NIST Digital Library of Mathematical Functions
6689 https://dlmf.nist.gov/13.2#E2
6691 Examples
6692 --------
6693 >>> import numpy as np
6694 >>> import scipy.special as sc
6696 It is one when `x` is zero:
6698 >>> sc.hyp1f1(0.5, 0.5, 0)
6699 1.0
6701 It is singular when `b` is a nonpositive integer.
6703 >>> sc.hyp1f1(0.5, -1, 0)
6704 inf
6706 It is a polynomial when `a` is a nonpositive integer.
6708 >>> a, b, x = -1, 0.5, np.array([1.0, 2.0, 3.0, 4.0])
6709 >>> sc.hyp1f1(a, b, x)
6710 array([-1., -3., -5., -7.])
6711 >>> 1 + (a / b) * x
6712 array([-1., -3., -5., -7.])
6714 It reduces to the exponential function when `a = b`.
6716 >>> sc.hyp1f1(2, 2, [1, 2, 3, 4])
6717 array([ 2.71828183, 7.3890561 , 20.08553692, 54.59815003])
6718 >>> np.exp([1, 2, 3, 4])
6719 array([ 2.71828183, 7.3890561 , 20.08553692, 54.59815003])
6721 """)
6723add_newdoc("hyp2f1",
6724 r"""
6725 hyp2f1(a, b, c, z, out=None)
6727 Gauss hypergeometric function 2F1(a, b; c; z)
6729 Parameters
6730 ----------
6731 a, b, c : array_like
6732 Arguments, should be real-valued.
6733 z : array_like
6734 Argument, real or complex.
6735 out : ndarray, optional
6736 Optional output array for the function values
6738 Returns
6739 -------
6740 hyp2f1 : scalar or ndarray
6741 The values of the gaussian hypergeometric function.
6743 See also
6744 --------
6745 hyp0f1 : confluent hypergeometric limit function.
6746 hyp1f1 : Kummer's (confluent hypergeometric) function.
6748 Notes
6749 -----
6750 This function is defined for :math:`|z| < 1` as
6752 .. math::
6754 \mathrm{hyp2f1}(a, b, c, z) = \sum_{n=0}^\infty
6755 \frac{(a)_n (b)_n}{(c)_n}\frac{z^n}{n!},
6757 and defined on the rest of the complex z-plane by analytic
6758 continuation [1]_.
6759 Here :math:`(\cdot)_n` is the Pochhammer symbol; see `poch`. When
6760 :math:`n` is an integer the result is a polynomial of degree :math:`n`.
6762 The implementation for complex values of ``z`` is described in [2]_,
6763 except for ``z`` in the region defined by
6765 .. math::
6767 0.9 <= \left|z\right| < 1.1,
6768 \left|1 - z\right| >= 0.9,
6769 \mathrm{real}(z) >= 0
6771 in which the implementation follows [4]_.
6773 References
6774 ----------
6775 .. [1] NIST Digital Library of Mathematical Functions
6776 https://dlmf.nist.gov/15.2
6777 .. [2] S. Zhang and J.M. Jin, "Computation of Special Functions", Wiley 1996
6778 .. [3] Cephes Mathematical Functions Library,
6779 http://www.netlib.org/cephes/
6780 .. [4] J.L. Lopez and N.M. Temme, "New series expansions of the Gauss
6781 hypergeometric function", Adv Comput Math 39, 349-365 (2013).
6782 https://doi.org/10.1007/s10444-012-9283-y
6784 Examples
6785 --------
6786 >>> import numpy as np
6787 >>> import scipy.special as sc
6789 It has poles when `c` is a negative integer.
6791 >>> sc.hyp2f1(1, 1, -2, 1)
6792 inf
6794 It is a polynomial when `a` or `b` is a negative integer.
6796 >>> a, b, c = -1, 1, 1.5
6797 >>> z = np.linspace(0, 1, 5)
6798 >>> sc.hyp2f1(a, b, c, z)
6799 array([1. , 0.83333333, 0.66666667, 0.5 , 0.33333333])
6800 >>> 1 + a * b * z / c
6801 array([1. , 0.83333333, 0.66666667, 0.5 , 0.33333333])
6803 It is symmetric in `a` and `b`.
6805 >>> a = np.linspace(0, 1, 5)
6806 >>> b = np.linspace(0, 1, 5)
6807 >>> sc.hyp2f1(a, b, 1, 0.5)
6808 array([1. , 1.03997334, 1.1803406 , 1.47074441, 2. ])
6809 >>> sc.hyp2f1(b, a, 1, 0.5)
6810 array([1. , 1.03997334, 1.1803406 , 1.47074441, 2. ])
6812 It contains many other functions as special cases.
6814 >>> z = 0.5
6815 >>> sc.hyp2f1(1, 1, 2, z)
6816 1.3862943611198901
6817 >>> -np.log(1 - z) / z
6818 1.3862943611198906
6820 >>> sc.hyp2f1(0.5, 1, 1.5, z**2)
6821 1.098612288668109
6822 >>> np.log((1 + z) / (1 - z)) / (2 * z)
6823 1.0986122886681098
6825 >>> sc.hyp2f1(0.5, 1, 1.5, -z**2)
6826 0.9272952180016117
6827 >>> np.arctan(z) / z
6828 0.9272952180016122
6830 """)
6832add_newdoc("hyperu",
6833 r"""
6834 hyperu(a, b, x, out=None)
6836 Confluent hypergeometric function U
6838 It is defined as the solution to the equation
6840 .. math::
6842 x \frac{d^2w}{dx^2} + (b - x) \frac{dw}{dx} - aw = 0
6844 which satisfies the property
6846 .. math::
6848 U(a, b, x) \sim x^{-a}
6850 as :math:`x \to \infty`. See [dlmf]_ for more details.
6852 Parameters
6853 ----------
6854 a, b : array_like
6855 Real-valued parameters
6856 x : array_like
6857 Real-valued argument
6858 out : ndarray, optional
6859 Optional output array for the function values
6861 Returns
6862 -------
6863 scalar or ndarray
6864 Values of `U`
6866 References
6867 ----------
6868 .. [dlmf] NIST Digital Library of Mathematics Functions
6869 https://dlmf.nist.gov/13.2#E6
6871 Examples
6872 --------
6873 >>> import numpy as np
6874 >>> import scipy.special as sc
6876 It has a branch cut along the negative `x` axis.
6878 >>> x = np.linspace(-0.1, -10, 5)
6879 >>> sc.hyperu(1, 1, x)
6880 array([nan, nan, nan, nan, nan])
6882 It approaches zero as `x` goes to infinity.
6884 >>> x = np.array([1, 10, 100])
6885 >>> sc.hyperu(1, 1, x)
6886 array([0.59634736, 0.09156333, 0.00990194])
6888 It satisfies Kummer's transformation.
6890 >>> a, b, x = 2, 1, 1
6891 >>> sc.hyperu(a, b, x)
6892 0.1926947246463881
6893 >>> x**(1 - b) * sc.hyperu(a - b + 1, 2 - b, x)
6894 0.1926947246463881
6896 """)
6898add_newdoc("i0",
6899 r"""
6900 i0(x, out=None)
6902 Modified Bessel function of order 0.
6904 Defined as,
6906 .. math::
6907 I_0(x) = \sum_{k=0}^\infty \frac{(x^2/4)^k}{(k!)^2} = J_0(\imath x),
6909 where :math:`J_0` is the Bessel function of the first kind of order 0.
6911 Parameters
6912 ----------
6913 x : array_like
6914 Argument (float)
6915 out : ndarray, optional
6916 Optional output array for the function values
6918 Returns
6919 -------
6920 I : scalar or ndarray
6921 Value of the modified Bessel function of order 0 at `x`.
6923 Notes
6924 -----
6925 The range is partitioned into the two intervals [0, 8] and (8, infinity).
6926 Chebyshev polynomial expansions are employed in each interval.
6928 This function is a wrapper for the Cephes [1]_ routine `i0`.
6930 See also
6931 --------
6932 iv: Modified Bessel function of any order
6933 i0e: Exponentially scaled modified Bessel function of order 0
6935 References
6936 ----------
6937 .. [1] Cephes Mathematical Functions Library,
6938 http://www.netlib.org/cephes/
6940 Examples
6941 --------
6942 Calculate the function at one point:
6944 >>> from scipy.special import i0
6945 >>> i0(1.)
6946 1.2660658777520082
6948 Calculate at several points:
6950 >>> import numpy as np
6951 >>> i0(np.array([-2., 0., 3.5]))
6952 array([2.2795853 , 1. , 7.37820343])
6954 Plot the function from -10 to 10.
6956 >>> import matplotlib.pyplot as plt
6957 >>> fig, ax = plt.subplots()
6958 >>> x = np.linspace(-10., 10., 1000)
6959 >>> y = i0(x)
6960 >>> ax.plot(x, y)
6961 >>> plt.show()
6963 """)
6965add_newdoc("i0e",
6966 """
6967 i0e(x, out=None)
6969 Exponentially scaled modified Bessel function of order 0.
6971 Defined as::
6973 i0e(x) = exp(-abs(x)) * i0(x).
6975 Parameters
6976 ----------
6977 x : array_like
6978 Argument (float)
6979 out : ndarray, optional
6980 Optional output array for the function values
6982 Returns
6983 -------
6984 I : scalar or ndarray
6985 Value of the exponentially scaled modified Bessel function of order 0
6986 at `x`.
6988 Notes
6989 -----
6990 The range is partitioned into the two intervals [0, 8] and (8, infinity).
6991 Chebyshev polynomial expansions are employed in each interval. The
6992 polynomial expansions used are the same as those in `i0`, but
6993 they are not multiplied by the dominant exponential factor.
6995 This function is a wrapper for the Cephes [1]_ routine `i0e`. `i0e`
6996 is useful for large arguments `x`: for these, `i0` quickly overflows.
6998 See also
6999 --------
7000 iv: Modified Bessel function of the first kind
7001 i0: Modified Bessel function of order 0
7003 References
7004 ----------
7005 .. [1] Cephes Mathematical Functions Library,
7006 http://www.netlib.org/cephes/
7008 Examples
7009 --------
7010 In the following example `i0` returns infinity whereas `i0e` still returns
7011 a finite number.
7013 >>> from scipy.special import i0, i0e
7014 >>> i0(1000.), i0e(1000.)
7015 (inf, 0.012617240455891257)
7017 Calculate the function at several points by providing a NumPy array or
7018 list for `x`:
7020 >>> import numpy as np
7021 >>> i0e(np.array([-2., 0., 3.]))
7022 array([0.30850832, 1. , 0.24300035])
7024 Plot the function from -10 to 10.
7026 >>> import matplotlib.pyplot as plt
7027 >>> fig, ax = plt.subplots()
7028 >>> x = np.linspace(-10., 10., 1000)
7029 >>> y = i0e(x)
7030 >>> ax.plot(x, y)
7031 >>> plt.show()
7032 """)
7034add_newdoc("i1",
7035 r"""
7036 i1(x, out=None)
7038 Modified Bessel function of order 1.
7040 Defined as,
7042 .. math::
7043 I_1(x) = \frac{1}{2}x \sum_{k=0}^\infty \frac{(x^2/4)^k}{k! (k + 1)!}
7044 = -\imath J_1(\imath x),
7046 where :math:`J_1` is the Bessel function of the first kind of order 1.
7048 Parameters
7049 ----------
7050 x : array_like
7051 Argument (float)
7052 out : ndarray, optional
7053 Optional output array for the function values
7055 Returns
7056 -------
7057 I : scalar or ndarray
7058 Value of the modified Bessel function of order 1 at `x`.
7060 Notes
7061 -----
7062 The range is partitioned into the two intervals [0, 8] and (8, infinity).
7063 Chebyshev polynomial expansions are employed in each interval.
7065 This function is a wrapper for the Cephes [1]_ routine `i1`.
7067 See also
7068 --------
7069 iv: Modified Bessel function of the first kind
7070 i1e: Exponentially scaled modified Bessel function of order 1
7072 References
7073 ----------
7074 .. [1] Cephes Mathematical Functions Library,
7075 http://www.netlib.org/cephes/
7077 Examples
7078 --------
7079 Calculate the function at one point:
7081 >>> from scipy.special import i1
7082 >>> i1(1.)
7083 0.5651591039924851
7085 Calculate the function at several points:
7087 >>> import numpy as np
7088 >>> i1(np.array([-2., 0., 6.]))
7089 array([-1.59063685, 0. , 61.34193678])
7091 Plot the function between -10 and 10.
7093 >>> import matplotlib.pyplot as plt
7094 >>> fig, ax = plt.subplots()
7095 >>> x = np.linspace(-10., 10., 1000)
7096 >>> y = i1(x)
7097 >>> ax.plot(x, y)
7098 >>> plt.show()
7100 """)
7102add_newdoc("i1e",
7103 """
7104 i1e(x, out=None)
7106 Exponentially scaled modified Bessel function of order 1.
7108 Defined as::
7110 i1e(x) = exp(-abs(x)) * i1(x)
7112 Parameters
7113 ----------
7114 x : array_like
7115 Argument (float)
7116 out : ndarray, optional
7117 Optional output array for the function values
7119 Returns
7120 -------
7121 I : scalar or ndarray
7122 Value of the exponentially scaled modified Bessel function of order 1
7123 at `x`.
7125 Notes
7126 -----
7127 The range is partitioned into the two intervals [0, 8] and (8, infinity).
7128 Chebyshev polynomial expansions are employed in each interval. The
7129 polynomial expansions used are the same as those in `i1`, but
7130 they are not multiplied by the dominant exponential factor.
7132 This function is a wrapper for the Cephes [1]_ routine `i1e`. `i1e`
7133 is useful for large arguments `x`: for these, `i1` quickly overflows.
7135 See also
7136 --------
7137 iv: Modified Bessel function of the first kind
7138 i1: Modified Bessel function of order 1
7140 References
7141 ----------
7142 .. [1] Cephes Mathematical Functions Library,
7143 http://www.netlib.org/cephes/
7145 Examples
7146 --------
7147 In the following example `i1` returns infinity whereas `i1e` still returns
7148 a finite number.
7150 >>> from scipy.special import i1, i1e
7151 >>> i1(1000.), i1e(1000.)
7152 (inf, 0.01261093025692863)
7154 Calculate the function at several points by providing a NumPy array or
7155 list for `x`:
7157 >>> import numpy as np
7158 >>> i1e(np.array([-2., 0., 6.]))
7159 array([-0.21526929, 0. , 0.15205146])
7161 Plot the function between -10 and 10.
7163 >>> import matplotlib.pyplot as plt
7164 >>> fig, ax = plt.subplots()
7165 >>> x = np.linspace(-10., 10., 1000)
7166 >>> y = i1e(x)
7167 >>> ax.plot(x, y)
7168 >>> plt.show()
7169 """)
7171add_newdoc("_igam_fac",
7172 """
7173 Internal function, do not use.
7174 """)
7176add_newdoc("it2i0k0",
7177 r"""
7178 it2i0k0(x, out=None)
7180 Integrals related to modified Bessel functions of order 0.
7182 Computes the integrals
7184 .. math::
7186 \int_0^x \frac{I_0(t) - 1}{t} dt \\
7187 \int_x^\infty \frac{K_0(t)}{t} dt.
7189 Parameters
7190 ----------
7191 x : array_like
7192 Values at which to evaluate the integrals.
7193 out : tuple of ndarrays, optional
7194 Optional output arrays for the function results.
7196 Returns
7197 -------
7198 ii0 : scalar or ndarray
7199 The integral for `i0`
7200 ik0 : scalar or ndarray
7201 The integral for `k0`
7203 References
7204 ----------
7205 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7206 Wiley 1996
7208 Examples
7209 --------
7210 Evaluate the functions at one point.
7212 >>> from scipy.special import it2i0k0
7213 >>> int_i, int_k = it2i0k0(1.)
7214 >>> int_i, int_k
7215 (0.12897944249456852, 0.2085182909001295)
7217 Evaluate the functions at several points.
7219 >>> import numpy as np
7220 >>> points = np.array([0.5, 1.5, 3.])
7221 >>> int_i, int_k = it2i0k0(points)
7222 >>> int_i, int_k
7223 (array([0.03149527, 0.30187149, 1.50012461]),
7224 array([0.66575102, 0.0823715 , 0.00823631]))
7226 Plot the functions from 0 to 5.
7228 >>> import matplotlib.pyplot as plt
7229 >>> fig, ax = plt.subplots()
7230 >>> x = np.linspace(0., 5., 1000)
7231 >>> int_i, int_k = it2i0k0(x)
7232 >>> ax.plot(x, int_i, label=r"$\int_0^x \frac{I_0(t)-1}{t}\,dt$")
7233 >>> ax.plot(x, int_k, label=r"$\int_x^{\infty} \frac{K_0(t)}{t}\,dt$")
7234 >>> ax.legend()
7235 >>> ax.set_ylim(0, 10)
7236 >>> plt.show()
7237 """)
7239add_newdoc("it2j0y0",
7240 r"""
7241 it2j0y0(x, out=None)
7243 Integrals related to Bessel functions of the first kind of order 0.
7245 Computes the integrals
7247 .. math::
7249 \int_0^x \frac{1 - J_0(t)}{t} dt \\
7250 \int_x^\infty \frac{Y_0(t)}{t} dt.
7252 For more on :math:`J_0` and :math:`Y_0` see `j0` and `y0`.
7254 Parameters
7255 ----------
7256 x : array_like
7257 Values at which to evaluate the integrals.
7258 out : tuple of ndarrays, optional
7259 Optional output arrays for the function results.
7261 Returns
7262 -------
7263 ij0 : scalar or ndarray
7264 The integral for `j0`
7265 iy0 : scalar or ndarray
7266 The integral for `y0`
7268 References
7269 ----------
7270 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7271 Wiley 1996
7273 Examples
7274 --------
7275 Evaluate the functions at one point.
7277 >>> from scipy.special import it2j0y0
7278 >>> int_j, int_y = it2j0y0(1.)
7279 >>> int_j, int_y
7280 (0.12116524699506871, 0.39527290169929336)
7282 Evaluate the functions at several points.
7284 >>> import numpy as np
7285 >>> points = np.array([0.5, 1.5, 3.])
7286 >>> int_j, int_y = it2j0y0(points)
7287 >>> int_j, int_y
7288 (array([0.03100699, 0.26227724, 0.85614669]),
7289 array([ 0.26968854, 0.29769696, -0.02987272]))
7291 Plot the functions from 0 to 10.
7293 >>> import matplotlib.pyplot as plt
7294 >>> fig, ax = plt.subplots()
7295 >>> x = np.linspace(0., 10., 1000)
7296 >>> int_j, int_y = it2j0y0(x)
7297 >>> ax.plot(x, int_j, label=r"$\int_0^x \frac{1-J_0(t)}{t}\,dt$")
7298 >>> ax.plot(x, int_y, label=r"$\int_x^{\infty} \frac{Y_0(t)}{t}\,dt$")
7299 >>> ax.legend()
7300 >>> ax.set_ylim(-2.5, 2.5)
7301 >>> plt.show()
7302 """)
7304add_newdoc("it2struve0",
7305 r"""
7306 it2struve0(x, out=None)
7308 Integral related to the Struve function of order 0.
7310 Returns the integral,
7312 .. math::
7313 \int_x^\infty \frac{H_0(t)}{t}\,dt
7315 where :math:`H_0` is the Struve function of order 0.
7317 Parameters
7318 ----------
7319 x : array_like
7320 Lower limit of integration.
7321 out : ndarray, optional
7322 Optional output array for the function values
7324 Returns
7325 -------
7326 I : scalar or ndarray
7327 The value of the integral.
7329 See also
7330 --------
7331 struve
7333 Notes
7334 -----
7335 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7336 Jin [1]_.
7338 References
7339 ----------
7340 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7341 Functions", John Wiley and Sons, 1996.
7342 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7344 Examples
7345 --------
7346 Evaluate the function at one point.
7348 >>> import numpy as np
7349 >>> from scipy.special import it2struve0
7350 >>> it2struve0(1.)
7351 0.9571973506383524
7353 Evaluate the function at several points by supplying
7354 an array for `x`.
7356 >>> points = np.array([1., 2., 3.5])
7357 >>> it2struve0(points)
7358 array([0.95719735, 0.46909296, 0.10366042])
7360 Plot the function from -10 to 10.
7362 >>> import matplotlib.pyplot as plt
7363 >>> x = np.linspace(-10., 10., 1000)
7364 >>> it2struve0_values = it2struve0(x)
7365 >>> fig, ax = plt.subplots()
7366 >>> ax.plot(x, it2struve0_values)
7367 >>> ax.set_xlabel(r'$x$')
7368 >>> ax.set_ylabel(r'$\int_x^{\infty}\frac{H_0(t)}{t}\,dt$')
7369 >>> plt.show()
7370 """)
7372add_newdoc(
7373 "itairy",
7374 r"""
7375 itairy(x, out=None)
7377 Integrals of Airy functions
7379 Calculates the integrals of Airy functions from 0 to `x`.
7381 Parameters
7382 ----------
7384 x : array_like
7385 Upper limit of integration (float).
7386 out : tuple of ndarray, optional
7387 Optional output arrays for the function values
7389 Returns
7390 -------
7391 Apt : scalar or ndarray
7392 Integral of Ai(t) from 0 to x.
7393 Bpt : scalar or ndarray
7394 Integral of Bi(t) from 0 to x.
7395 Ant : scalar or ndarray
7396 Integral of Ai(-t) from 0 to x.
7397 Bnt : scalar or ndarray
7398 Integral of Bi(-t) from 0 to x.
7400 Notes
7401 -----
7403 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7404 Jin [1]_.
7406 References
7407 ----------
7409 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7410 Functions", John Wiley and Sons, 1996.
7411 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7413 Examples
7414 --------
7415 Compute the functions at ``x=1.``.
7417 >>> import numpy as np
7418 >>> from scipy.special import itairy
7419 >>> import matplotlib.pyplot as plt
7420 >>> apt, bpt, ant, bnt = itairy(1.)
7421 >>> apt, bpt, ant, bnt
7422 (0.23631734191710949,
7423 0.8727691167380077,
7424 0.46567398346706845,
7425 0.3730050096342943)
7427 Compute the functions at several points by providing a NumPy array for `x`.
7429 >>> x = np.array([1., 1.5, 2.5, 5])
7430 >>> apt, bpt, ant, bnt = itairy(x)
7431 >>> apt, bpt, ant, bnt
7432 (array([0.23631734, 0.28678675, 0.324638 , 0.33328759]),
7433 array([ 0.87276912, 1.62470809, 5.20906691, 321.47831857]),
7434 array([0.46567398, 0.72232876, 0.93187776, 0.7178822 ]),
7435 array([ 0.37300501, 0.35038814, -0.02812939, 0.15873094]))
7437 Plot the functions from -10 to 10.
7439 >>> x = np.linspace(-10, 10, 500)
7440 >>> apt, bpt, ant, bnt = itairy(x)
7441 >>> fig, ax = plt.subplots(figsize=(6, 5))
7442 >>> ax.plot(x, apt, label="$\int_0^x\, Ai(t)\, dt$")
7443 >>> ax.plot(x, bpt, ls="dashed", label="$\int_0^x\, Bi(t)\, dt$")
7444 >>> ax.plot(x, ant, ls="dashdot", label="$\int_0^x\, Ai(-t)\, dt$")
7445 >>> ax.plot(x, bnt, ls="dotted", label="$\int_0^x\, Bi(-t)\, dt$")
7446 >>> ax.set_ylim(-2, 1.5)
7447 >>> ax.legend(loc="lower right")
7448 >>> plt.show()
7449 """)
7451add_newdoc("iti0k0",
7452 r"""
7453 iti0k0(x, out=None)
7455 Integrals of modified Bessel functions of order 0.
7457 Computes the integrals
7459 .. math::
7461 \int_0^x I_0(t) dt \\
7462 \int_0^x K_0(t) dt.
7464 For more on :math:`I_0` and :math:`K_0` see `i0` and `k0`.
7466 Parameters
7467 ----------
7468 x : array_like
7469 Values at which to evaluate the integrals.
7470 out : tuple of ndarrays, optional
7471 Optional output arrays for the function results.
7473 Returns
7474 -------
7475 ii0 : scalar or ndarray
7476 The integral for `i0`
7477 ik0 : scalar or ndarray
7478 The integral for `k0`
7480 References
7481 ----------
7482 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7483 Wiley 1996
7485 Examples
7486 --------
7487 Evaluate the functions at one point.
7489 >>> from scipy.special import iti0k0
7490 >>> int_i, int_k = iti0k0(1.)
7491 >>> int_i, int_k
7492 (1.0865210970235892, 1.2425098486237771)
7494 Evaluate the functions at several points.
7496 >>> import numpy as np
7497 >>> points = np.array([0., 1.5, 3.])
7498 >>> int_i, int_k = iti0k0(points)
7499 >>> int_i, int_k
7500 (array([0. , 1.80606937, 6.16096149]),
7501 array([0. , 1.39458246, 1.53994809]))
7503 Plot the functions from 0 to 5.
7505 >>> import matplotlib.pyplot as plt
7506 >>> fig, ax = plt.subplots()
7507 >>> x = np.linspace(0., 5., 1000)
7508 >>> int_i, int_k = iti0k0(x)
7509 >>> ax.plot(x, int_i, label="$\int_0^x I_0(t)\,dt$")
7510 >>> ax.plot(x, int_k, label="$\int_0^x K_0(t)\,dt$")
7511 >>> ax.legend()
7512 >>> plt.show()
7513 """)
7515add_newdoc("itj0y0",
7516 r"""
7517 itj0y0(x, out=None)
7519 Integrals of Bessel functions of the first kind of order 0.
7521 Computes the integrals
7523 .. math::
7525 \int_0^x J_0(t) dt \\
7526 \int_0^x Y_0(t) dt.
7528 For more on :math:`J_0` and :math:`Y_0` see `j0` and `y0`.
7530 Parameters
7531 ----------
7532 x : array_like
7533 Values at which to evaluate the integrals.
7534 out : tuple of ndarrays, optional
7535 Optional output arrays for the function results.
7537 Returns
7538 -------
7539 ij0 : scalar or ndarray
7540 The integral of `j0`
7541 iy0 : scalar or ndarray
7542 The integral of `y0`
7544 References
7545 ----------
7546 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7547 Wiley 1996
7549 Examples
7550 --------
7551 Evaluate the functions at one point.
7553 >>> from scipy.special import itj0y0
7554 >>> int_j, int_y = itj0y0(1.)
7555 >>> int_j, int_y
7556 (0.9197304100897596, -0.637069376607422)
7558 Evaluate the functions at several points.
7560 >>> import numpy as np
7561 >>> points = np.array([0., 1.5, 3.])
7562 >>> int_j, int_y = itj0y0(points)
7563 >>> int_j, int_y
7564 (array([0. , 1.24144951, 1.38756725]),
7565 array([ 0. , -0.51175903, 0.19765826]))
7567 Plot the functions from 0 to 10.
7569 >>> import matplotlib.pyplot as plt
7570 >>> fig, ax = plt.subplots()
7571 >>> x = np.linspace(0., 10., 1000)
7572 >>> int_j, int_y = itj0y0(x)
7573 >>> ax.plot(x, int_j, label="$\int_0^x J_0(t)\,dt$")
7574 >>> ax.plot(x, int_y, label="$\int_0^x Y_0(t)\,dt$")
7575 >>> ax.legend()
7576 >>> plt.show()
7578 """)
7580add_newdoc("itmodstruve0",
7581 r"""
7582 itmodstruve0(x, out=None)
7584 Integral of the modified Struve function of order 0.
7586 .. math::
7587 I = \int_0^x L_0(t)\,dt
7589 Parameters
7590 ----------
7591 x : array_like
7592 Upper limit of integration (float).
7593 out : ndarray, optional
7594 Optional output array for the function values
7596 Returns
7597 -------
7598 I : scalar or ndarray
7599 The integral of :math:`L_0` from 0 to `x`.
7601 Notes
7602 -----
7603 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7604 Jin [1]_.
7606 See Also
7607 --------
7608 modstruve: Modified Struve function which is integrated by this function
7610 References
7611 ----------
7612 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7613 Functions", John Wiley and Sons, 1996.
7614 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7616 Examples
7617 --------
7618 Evaluate the function at one point.
7620 >>> import numpy as np
7621 >>> from scipy.special import itmodstruve0
7622 >>> itmodstruve0(1.)
7623 0.3364726286440384
7625 Evaluate the function at several points by supplying
7626 an array for `x`.
7628 >>> points = np.array([1., 2., 3.5])
7629 >>> itmodstruve0(points)
7630 array([0.33647263, 1.588285 , 7.60382578])
7632 Plot the function from -10 to 10.
7634 >>> import matplotlib.pyplot as plt
7635 >>> x = np.linspace(-10., 10., 1000)
7636 >>> itmodstruve0_values = itmodstruve0(x)
7637 >>> fig, ax = plt.subplots()
7638 >>> ax.plot(x, itmodstruve0_values)
7639 >>> ax.set_xlabel(r'$x$')
7640 >>> ax.set_ylabel(r'$\int_0^xL_0(t)\,dt$')
7641 >>> plt.show()
7642 """)
7644add_newdoc("itstruve0",
7645 r"""
7646 itstruve0(x, out=None)
7648 Integral of the Struve function of order 0.
7650 .. math::
7651 I = \int_0^x H_0(t)\,dt
7653 Parameters
7654 ----------
7655 x : array_like
7656 Upper limit of integration (float).
7657 out : ndarray, optional
7658 Optional output array for the function values
7660 Returns
7661 -------
7662 I : scalar or ndarray
7663 The integral of :math:`H_0` from 0 to `x`.
7665 See also
7666 --------
7667 struve: Function which is integrated by this function
7669 Notes
7670 -----
7671 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7672 Jin [1]_.
7674 References
7675 ----------
7676 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7677 Functions", John Wiley and Sons, 1996.
7678 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7680 Examples
7681 --------
7682 Evaluate the function at one point.
7684 >>> import numpy as np
7685 >>> from scipy.special import itstruve0
7686 >>> itstruve0(1.)
7687 0.30109042670805547
7689 Evaluate the function at several points by supplying
7690 an array for `x`.
7692 >>> points = np.array([1., 2., 3.5])
7693 >>> itstruve0(points)
7694 array([0.30109043, 1.01870116, 1.96804581])
7696 Plot the function from -20 to 20.
7698 >>> import matplotlib.pyplot as plt
7699 >>> x = np.linspace(-20., 20., 1000)
7700 >>> istruve0_values = itstruve0(x)
7701 >>> fig, ax = plt.subplots()
7702 >>> ax.plot(x, istruve0_values)
7703 >>> ax.set_xlabel(r'$x$')
7704 >>> ax.set_ylabel(r'$\int_0^{x}H_0(t)\,dt$')
7705 >>> plt.show()
7706 """)
7708add_newdoc("iv",
7709 r"""
7710 iv(v, z, out=None)
7712 Modified Bessel function of the first kind of real order.
7714 Parameters
7715 ----------
7716 v : array_like
7717 Order. If `z` is of real type and negative, `v` must be integer
7718 valued.
7719 z : array_like of float or complex
7720 Argument.
7721 out : ndarray, optional
7722 Optional output array for the function values
7724 Returns
7725 -------
7726 scalar or ndarray
7727 Values of the modified Bessel function.
7729 Notes
7730 -----
7731 For real `z` and :math:`v \in [-50, 50]`, the evaluation is carried out
7732 using Temme's method [1]_. For larger orders, uniform asymptotic
7733 expansions are applied.
7735 For complex `z` and positive `v`, the AMOS [2]_ `zbesi` routine is
7736 called. It uses a power series for small `z`, the asymptotic expansion
7737 for large `abs(z)`, the Miller algorithm normalized by the Wronskian
7738 and a Neumann series for intermediate magnitudes, and the uniform
7739 asymptotic expansions for :math:`I_v(z)` and :math:`J_v(z)` for large
7740 orders. Backward recurrence is used to generate sequences or reduce
7741 orders when necessary.
7743 The calculations above are done in the right half plane and continued
7744 into the left half plane by the formula,
7746 .. math:: I_v(z \exp(\pm\imath\pi)) = \exp(\pm\pi v) I_v(z)
7748 (valid when the real part of `z` is positive). For negative `v`, the
7749 formula
7751 .. math:: I_{-v}(z) = I_v(z) + \frac{2}{\pi} \sin(\pi v) K_v(z)
7753 is used, where :math:`K_v(z)` is the modified Bessel function of the
7754 second kind, evaluated using the AMOS routine `zbesk`.
7756 See also
7757 --------
7758 ive : This function with leading exponential behavior stripped off.
7759 i0 : Faster version of this function for order 0.
7760 i1 : Faster version of this function for order 1.
7762 References
7763 ----------
7764 .. [1] Temme, Journal of Computational Physics, vol 21, 343 (1976)
7765 .. [2] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
7766 of a Complex Argument and Nonnegative Order",
7767 http://netlib.org/amos/
7769 Examples
7770 --------
7771 Evaluate the function of order 0 at one point.
7773 >>> from scipy.special import iv
7774 >>> iv(0, 1.)
7775 1.2660658777520084
7777 Evaluate the function at one point for different orders.
7779 >>> iv(0, 1.), iv(1, 1.), iv(1.5, 1.)
7780 (1.2660658777520084, 0.565159103992485, 0.2935253263474798)
7782 The evaluation for different orders can be carried out in one call by
7783 providing a list or NumPy array as argument for the `v` parameter:
7785 >>> iv([0, 1, 1.5], 1.)
7786 array([1.26606588, 0.5651591 , 0.29352533])
7788 Evaluate the function at several points for order 0 by providing an
7789 array for `z`.
7791 >>> import numpy as np
7792 >>> points = np.array([-2., 0., 3.])
7793 >>> iv(0, points)
7794 array([2.2795853 , 1. , 4.88079259])
7796 If `z` is an array, the order parameter `v` must be broadcastable to
7797 the correct shape if different orders shall be computed in one call.
7798 To calculate the orders 0 and 1 for an 1D array:
7800 >>> orders = np.array([[0], [1]])
7801 >>> orders.shape
7802 (2, 1)
7804 >>> iv(orders, points)
7805 array([[ 2.2795853 , 1. , 4.88079259],
7806 [-1.59063685, 0. , 3.95337022]])
7808 Plot the functions of order 0 to 3 from -5 to 5.
7810 >>> import matplotlib.pyplot as plt
7811 >>> fig, ax = plt.subplots()
7812 >>> x = np.linspace(-5., 5., 1000)
7813 >>> for i in range(4):
7814 ... ax.plot(x, iv(i, x), label=f'$I_{i!r}$')
7815 >>> ax.legend()
7816 >>> plt.show()
7818 """)
7820add_newdoc("ive",
7821 r"""
7822 ive(v, z, out=None)
7824 Exponentially scaled modified Bessel function of the first kind.
7826 Defined as::
7828 ive(v, z) = iv(v, z) * exp(-abs(z.real))
7830 For imaginary numbers without a real part, returns the unscaled
7831 Bessel function of the first kind `iv`.
7833 Parameters
7834 ----------
7835 v : array_like of float
7836 Order.
7837 z : array_like of float or complex
7838 Argument.
7839 out : ndarray, optional
7840 Optional output array for the function values
7842 Returns
7843 -------
7844 scalar or ndarray
7845 Values of the exponentially scaled modified Bessel function.
7847 Notes
7848 -----
7849 For positive `v`, the AMOS [1]_ `zbesi` routine is called. It uses a
7850 power series for small `z`, the asymptotic expansion for large
7851 `abs(z)`, the Miller algorithm normalized by the Wronskian and a
7852 Neumann series for intermediate magnitudes, and the uniform asymptotic
7853 expansions for :math:`I_v(z)` and :math:`J_v(z)` for large orders.
7854 Backward recurrence is used to generate sequences or reduce orders when
7855 necessary.
7857 The calculations above are done in the right half plane and continued
7858 into the left half plane by the formula,
7860 .. math:: I_v(z \exp(\pm\imath\pi)) = \exp(\pm\pi v) I_v(z)
7862 (valid when the real part of `z` is positive). For negative `v`, the
7863 formula
7865 .. math:: I_{-v}(z) = I_v(z) + \frac{2}{\pi} \sin(\pi v) K_v(z)
7867 is used, where :math:`K_v(z)` is the modified Bessel function of the
7868 second kind, evaluated using the AMOS routine `zbesk`.
7870 `ive` is useful for large arguments `z`: for these, `iv` easily overflows,
7871 while `ive` does not due to the exponential scaling.
7873 See also
7874 --------
7875 iv: Modified Bessel function of the first kind
7876 i0e: Faster implementation of this function for order 0
7877 i1e: Faster implementation of this function for order 1
7879 References
7880 ----------
7881 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
7882 of a Complex Argument and Nonnegative Order",
7883 http://netlib.org/amos/
7885 Examples
7886 --------
7887 In the following example `iv` returns infinity whereas `ive` still returns
7888 a finite number.
7890 >>> from scipy.special import iv, ive
7891 >>> import numpy as np
7892 >>> import matplotlib.pyplot as plt
7893 >>> iv(3, 1000.), ive(3, 1000.)
7894 (inf, 0.01256056218254712)
7896 Evaluate the function at one point for different orders by
7897 providing a list or NumPy array as argument for the `v` parameter:
7899 >>> ive([0, 1, 1.5], 1.)
7900 array([0.46575961, 0.20791042, 0.10798193])
7902 Evaluate the function at several points for order 0 by providing an
7903 array for `z`.
7905 >>> points = np.array([-2., 0., 3.])
7906 >>> ive(0, points)
7907 array([0.30850832, 1. , 0.24300035])
7909 Evaluate the function at several points for different orders by
7910 providing arrays for both `v` for `z`. Both arrays have to be
7911 broadcastable to the correct shape. To calculate the orders 0, 1
7912 and 2 for a 1D array of points:
7914 >>> ive([[0], [1], [2]], points)
7915 array([[ 0.30850832, 1. , 0.24300035],
7916 [-0.21526929, 0. , 0.19682671],
7917 [ 0.09323903, 0. , 0.11178255]])
7919 Plot the functions of order 0 to 3 from -5 to 5.
7921 >>> fig, ax = plt.subplots()
7922 >>> x = np.linspace(-5., 5., 1000)
7923 >>> for i in range(4):
7924 ... ax.plot(x, ive(i, x), label=f'$I_{i!r}(z)\cdot e^{{-|z|}}$')
7925 >>> ax.legend()
7926 >>> ax.set_xlabel(r"$z$")
7927 >>> plt.show()
7928 """)
7930add_newdoc("j0",
7931 r"""
7932 j0(x, out=None)
7934 Bessel function of the first kind of order 0.
7936 Parameters
7937 ----------
7938 x : array_like
7939 Argument (float).
7940 out : ndarray, optional
7941 Optional output array for the function values
7943 Returns
7944 -------
7945 J : scalar or ndarray
7946 Value of the Bessel function of the first kind of order 0 at `x`.
7948 Notes
7949 -----
7950 The domain is divided into the intervals [0, 5] and (5, infinity). In the
7951 first interval the following rational approximation is used:
7953 .. math::
7955 J_0(x) \approx (w - r_1^2)(w - r_2^2) \frac{P_3(w)}{Q_8(w)},
7957 where :math:`w = x^2` and :math:`r_1`, :math:`r_2` are the zeros of
7958 :math:`J_0`, and :math:`P_3` and :math:`Q_8` are polynomials of degrees 3
7959 and 8, respectively.
7961 In the second interval, the Hankel asymptotic expansion is employed with
7962 two rational functions of degree 6/6 and 7/7.
7964 This function is a wrapper for the Cephes [1]_ routine `j0`.
7965 It should not be confused with the spherical Bessel functions (see
7966 `spherical_jn`).
7968 See also
7969 --------
7970 jv : Bessel function of real order and complex argument.
7971 spherical_jn : spherical Bessel functions.
7973 References
7974 ----------
7975 .. [1] Cephes Mathematical Functions Library,
7976 http://www.netlib.org/cephes/
7978 Examples
7979 --------
7980 Calculate the function at one point:
7982 >>> from scipy.special import j0
7983 >>> j0(1.)
7984 0.7651976865579665
7986 Calculate the function at several points:
7988 >>> import numpy as np
7989 >>> j0(np.array([-2., 0., 4.]))
7990 array([ 0.22389078, 1. , -0.39714981])
7992 Plot the function from -20 to 20.
7994 >>> import matplotlib.pyplot as plt
7995 >>> fig, ax = plt.subplots()
7996 >>> x = np.linspace(-20., 20., 1000)
7997 >>> y = j0(x)
7998 >>> ax.plot(x, y)
7999 >>> plt.show()
8001 """)
8003add_newdoc("j1",
8004 """
8005 j1(x, out=None)
8007 Bessel function of the first kind of order 1.
8009 Parameters
8010 ----------
8011 x : array_like
8012 Argument (float).
8013 out : ndarray, optional
8014 Optional output array for the function values
8016 Returns
8017 -------
8018 J : scalar or ndarray
8019 Value of the Bessel function of the first kind of order 1 at `x`.
8021 Notes
8022 -----
8023 The domain is divided into the intervals [0, 8] and (8, infinity). In the
8024 first interval a 24 term Chebyshev expansion is used. In the second, the
8025 asymptotic trigonometric representation is employed using two rational
8026 functions of degree 5/5.
8028 This function is a wrapper for the Cephes [1]_ routine `j1`.
8029 It should not be confused with the spherical Bessel functions (see
8030 `spherical_jn`).
8032 See also
8033 --------
8034 jv: Bessel function of the first kind
8035 spherical_jn: spherical Bessel functions.
8037 References
8038 ----------
8039 .. [1] Cephes Mathematical Functions Library,
8040 http://www.netlib.org/cephes/
8042 Examples
8043 --------
8044 Calculate the function at one point:
8046 >>> from scipy.special import j1
8047 >>> j1(1.)
8048 0.44005058574493355
8050 Calculate the function at several points:
8052 >>> import numpy as np
8053 >>> j1(np.array([-2., 0., 4.]))
8054 array([-0.57672481, 0. , -0.06604333])
8056 Plot the function from -20 to 20.
8058 >>> import matplotlib.pyplot as plt
8059 >>> fig, ax = plt.subplots()
8060 >>> x = np.linspace(-20., 20., 1000)
8061 >>> y = j1(x)
8062 >>> ax.plot(x, y)
8063 >>> plt.show()
8065 """)
8067add_newdoc("jn",
8068 """
8069 jn(n, x, out=None)
8071 Bessel function of the first kind of integer order and real argument.
8073 Parameters
8074 ----------
8075 n : array_like
8076 order of the Bessel function
8077 x : array_like
8078 argument of the Bessel function
8079 out : ndarray, optional
8080 Optional output array for the function values
8082 Returns
8083 -------
8084 scalar or ndarray
8085 The value of the bessel function
8087 See also
8088 --------
8089 jv
8090 spherical_jn : spherical Bessel functions.
8092 Notes
8093 -----
8094 `jn` is an alias of `jv`.
8095 Not to be confused with the spherical Bessel functions (see
8096 `spherical_jn`).
8098 """)
8100add_newdoc("jv",
8101 r"""
8102 jv(v, z, out=None)
8104 Bessel function of the first kind of real order and complex argument.
8106 Parameters
8107 ----------
8108 v : array_like
8109 Order (float).
8110 z : array_like
8111 Argument (float or complex).
8112 out : ndarray, optional
8113 Optional output array for the function values
8115 Returns
8116 -------
8117 J : scalar or ndarray
8118 Value of the Bessel function, :math:`J_v(z)`.
8120 See also
8121 --------
8122 jve : :math:`J_v` with leading exponential behavior stripped off.
8123 spherical_jn : spherical Bessel functions.
8124 j0 : faster version of this function for order 0.
8125 j1 : faster version of this function for order 1.
8127 Notes
8128 -----
8129 For positive `v` values, the computation is carried out using the AMOS
8130 [1]_ `zbesj` routine, which exploits the connection to the modified
8131 Bessel function :math:`I_v`,
8133 .. math::
8134 J_v(z) = \exp(v\pi\imath/2) I_v(-\imath z)\qquad (\Im z > 0)
8136 J_v(z) = \exp(-v\pi\imath/2) I_v(\imath z)\qquad (\Im z < 0)
8138 For negative `v` values the formula,
8140 .. math:: J_{-v}(z) = J_v(z) \cos(\pi v) - Y_v(z) \sin(\pi v)
8142 is used, where :math:`Y_v(z)` is the Bessel function of the second
8143 kind, computed using the AMOS routine `zbesy`. Note that the second
8144 term is exactly zero for integer `v`; to improve accuracy the second
8145 term is explicitly omitted for `v` values such that `v = floor(v)`.
8147 Not to be confused with the spherical Bessel functions (see `spherical_jn`).
8149 References
8150 ----------
8151 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
8152 of a Complex Argument and Nonnegative Order",
8153 http://netlib.org/amos/
8155 Examples
8156 --------
8157 Evaluate the function of order 0 at one point.
8159 >>> from scipy.special import jv
8160 >>> jv(0, 1.)
8161 0.7651976865579666
8163 Evaluate the function at one point for different orders.
8165 >>> jv(0, 1.), jv(1, 1.), jv(1.5, 1.)
8166 (0.7651976865579666, 0.44005058574493355, 0.24029783912342725)
8168 The evaluation for different orders can be carried out in one call by
8169 providing a list or NumPy array as argument for the `v` parameter:
8171 >>> jv([0, 1, 1.5], 1.)
8172 array([0.76519769, 0.44005059, 0.24029784])
8174 Evaluate the function at several points for order 0 by providing an
8175 array for `z`.
8177 >>> import numpy as np
8178 >>> points = np.array([-2., 0., 3.])
8179 >>> jv(0, points)
8180 array([ 0.22389078, 1. , -0.26005195])
8182 If `z` is an array, the order parameter `v` must be broadcastable to
8183 the correct shape if different orders shall be computed in one call.
8184 To calculate the orders 0 and 1 for an 1D array:
8186 >>> orders = np.array([[0], [1]])
8187 >>> orders.shape
8188 (2, 1)
8190 >>> jv(orders, points)
8191 array([[ 0.22389078, 1. , -0.26005195],
8192 [-0.57672481, 0. , 0.33905896]])
8194 Plot the functions of order 0 to 3 from -10 to 10.
8196 >>> import matplotlib.pyplot as plt
8197 >>> fig, ax = plt.subplots()
8198 >>> x = np.linspace(-10., 10., 1000)
8199 >>> for i in range(4):
8200 ... ax.plot(x, jv(i, x), label=f'$J_{i!r}$')
8201 >>> ax.legend()
8202 >>> plt.show()
8204 """)
8206add_newdoc("jve",
8207 r"""
8208 jve(v, z, out=None)
8210 Exponentially scaled Bessel function of the first kind of order `v`.
8212 Defined as::
8214 jve(v, z) = jv(v, z) * exp(-abs(z.imag))
8216 Parameters
8217 ----------
8218 v : array_like
8219 Order (float).
8220 z : array_like
8221 Argument (float or complex).
8222 out : ndarray, optional
8223 Optional output array for the function values
8225 Returns
8226 -------
8227 J : scalar or ndarray
8228 Value of the exponentially scaled Bessel function.
8230 See also
8231 --------
8232 jv: Unscaled Bessel function of the first kind
8234 Notes
8235 -----
8236 For positive `v` values, the computation is carried out using the AMOS
8237 [1]_ `zbesj` routine, which exploits the connection to the modified
8238 Bessel function :math:`I_v`,
8240 .. math::
8241 J_v(z) = \exp(v\pi\imath/2) I_v(-\imath z)\qquad (\Im z > 0)
8243 J_v(z) = \exp(-v\pi\imath/2) I_v(\imath z)\qquad (\Im z < 0)
8245 For negative `v` values the formula,
8247 .. math:: J_{-v}(z) = J_v(z) \cos(\pi v) - Y_v(z) \sin(\pi v)
8249 is used, where :math:`Y_v(z)` is the Bessel function of the second
8250 kind, computed using the AMOS routine `zbesy`. Note that the second
8251 term is exactly zero for integer `v`; to improve accuracy the second
8252 term is explicitly omitted for `v` values such that `v = floor(v)`.
8254 Exponentially scaled Bessel functions are useful for large arguments `z`:
8255 for these, the unscaled Bessel functions can easily under-or overflow.
8257 References
8258 ----------
8259 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
8260 of a Complex Argument and Nonnegative Order",
8261 http://netlib.org/amos/
8263 Examples
8264 --------
8265 Compare the output of `jv` and `jve` for large complex arguments for `z`
8266 by computing their values for order ``v=1`` at ``z=1000j``. We see that
8267 `jv` overflows but `jve` returns a finite number:
8269 >>> import numpy as np
8270 >>> from scipy.special import jv, jve
8271 >>> v = 1
8272 >>> z = 1000j
8273 >>> jv(v, z), jve(v, z)
8274 ((inf+infj), (7.721967686709077e-19+0.012610930256928629j))
8276 For real arguments for `z`, `jve` returns the same as `jv`.
8278 >>> v, z = 1, 1000
8279 >>> jv(v, z), jve(v, z)
8280 (0.004728311907089523, 0.004728311907089523)
8282 The function can be evaluated for several orders at the same time by
8283 providing a list or NumPy array for `v`:
8285 >>> jve([1, 3, 5], 1j)
8286 array([1.27304208e-17+2.07910415e-01j, -4.99352086e-19-8.15530777e-03j,
8287 6.11480940e-21+9.98657141e-05j])
8289 In the same way, the function can be evaluated at several points in one
8290 call by providing a list or NumPy array for `z`:
8292 >>> jve(1, np.array([1j, 2j, 3j]))
8293 array([1.27308412e-17+0.20791042j, 1.31814423e-17+0.21526929j,
8294 1.20521602e-17+0.19682671j])
8296 It is also possible to evaluate several orders at several points
8297 at the same time by providing arrays for `v` and `z` with
8298 compatible shapes for broadcasting. Compute `jve` for two different orders
8299 `v` and three points `z` resulting in a 2x3 array.
8301 >>> v = np.array([[1], [3]])
8302 >>> z = np.array([1j, 2j, 3j])
8303 >>> v.shape, z.shape
8304 ((2, 1), (3,))
8306 >>> jve(v, z)
8307 array([[1.27304208e-17+0.20791042j, 1.31810070e-17+0.21526929j,
8308 1.20517622e-17+0.19682671j],
8309 [-4.99352086e-19-0.00815531j, -1.76289571e-18-0.02879122j,
8310 -2.92578784e-18-0.04778332j]])
8311 """)
8313add_newdoc("k0",
8314 r"""
8315 k0(x, out=None)
8317 Modified Bessel function of the second kind of order 0, :math:`K_0`.
8319 This function is also sometimes referred to as the modified Bessel
8320 function of the third kind of order 0.
8322 Parameters
8323 ----------
8324 x : array_like
8325 Argument (float).
8326 out : ndarray, optional
8327 Optional output array for the function values
8329 Returns
8330 -------
8331 K : scalar or ndarray
8332 Value of the modified Bessel function :math:`K_0` at `x`.
8334 Notes
8335 -----
8336 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8337 Chebyshev polynomial expansions are employed in each interval.
8339 This function is a wrapper for the Cephes [1]_ routine `k0`.
8341 See also
8342 --------
8343 kv: Modified Bessel function of the second kind of any order
8344 k0e: Exponentially scaled modified Bessel function of the second kind
8346 References
8347 ----------
8348 .. [1] Cephes Mathematical Functions Library,
8349 http://www.netlib.org/cephes/
8351 Examples
8352 --------
8353 Calculate the function at one point:
8355 >>> from scipy.special import k0
8356 >>> k0(1.)
8357 0.42102443824070823
8359 Calculate the function at several points:
8361 >>> import numpy as np
8362 >>> k0(np.array([0.5, 2., 3.]))
8363 array([0.92441907, 0.11389387, 0.0347395 ])
8365 Plot the function from 0 to 10.
8367 >>> import matplotlib.pyplot as plt
8368 >>> fig, ax = plt.subplots()
8369 >>> x = np.linspace(0., 10., 1000)
8370 >>> y = k0(x)
8371 >>> ax.plot(x, y)
8372 >>> plt.show()
8374 """)
8376add_newdoc("k0e",
8377 """
8378 k0e(x, out=None)
8380 Exponentially scaled modified Bessel function K of order 0
8382 Defined as::
8384 k0e(x) = exp(x) * k0(x).
8386 Parameters
8387 ----------
8388 x : array_like
8389 Argument (float)
8390 out : ndarray, optional
8391 Optional output array for the function values
8393 Returns
8394 -------
8395 K : scalar or ndarray
8396 Value of the exponentially scaled modified Bessel function K of order
8397 0 at `x`.
8399 Notes
8400 -----
8401 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8402 Chebyshev polynomial expansions are employed in each interval.
8404 This function is a wrapper for the Cephes [1]_ routine `k0e`. `k0e` is
8405 useful for large arguments: for these, `k0` easily underflows.
8407 See also
8408 --------
8409 kv: Modified Bessel function of the second kind of any order
8410 k0: Modified Bessel function of the second kind
8412 References
8413 ----------
8414 .. [1] Cephes Mathematical Functions Library,
8415 http://www.netlib.org/cephes/
8417 Examples
8418 --------
8419 In the following example `k0` returns 0 whereas `k0e` still returns a
8420 useful finite number:
8422 >>> from scipy.special import k0, k0e
8423 >>> k0(1000.), k0e(1000)
8424 (0., 0.03962832160075422)
8426 Calculate the function at several points by providing a NumPy array or
8427 list for `x`:
8429 >>> import numpy as np
8430 >>> k0e(np.array([0.5, 2., 3.]))
8431 array([1.52410939, 0.84156822, 0.6977616 ])
8433 Plot the function from 0 to 10.
8435 >>> import matplotlib.pyplot as plt
8436 >>> fig, ax = plt.subplots()
8437 >>> x = np.linspace(0., 10., 1000)
8438 >>> y = k0e(x)
8439 >>> ax.plot(x, y)
8440 >>> plt.show()
8441 """)
8443add_newdoc("k1",
8444 """
8445 k1(x, out=None)
8447 Modified Bessel function of the second kind of order 1, :math:`K_1(x)`.
8449 Parameters
8450 ----------
8451 x : array_like
8452 Argument (float)
8453 out : ndarray, optional
8454 Optional output array for the function values
8456 Returns
8457 -------
8458 K : scalar or ndarray
8459 Value of the modified Bessel function K of order 1 at `x`.
8461 Notes
8462 -----
8463 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8464 Chebyshev polynomial expansions are employed in each interval.
8466 This function is a wrapper for the Cephes [1]_ routine `k1`.
8468 See also
8469 --------
8470 kv: Modified Bessel function of the second kind of any order
8471 k1e: Exponentially scaled modified Bessel function K of order 1
8473 References
8474 ----------
8475 .. [1] Cephes Mathematical Functions Library,
8476 http://www.netlib.org/cephes/
8478 Examples
8479 --------
8480 Calculate the function at one point:
8482 >>> from scipy.special import k1
8483 >>> k1(1.)
8484 0.6019072301972346
8486 Calculate the function at several points:
8488 >>> import numpy as np
8489 >>> k1(np.array([0.5, 2., 3.]))
8490 array([1.65644112, 0.13986588, 0.04015643])
8492 Plot the function from 0 to 10.
8494 >>> import matplotlib.pyplot as plt
8495 >>> fig, ax = plt.subplots()
8496 >>> x = np.linspace(0., 10., 1000)
8497 >>> y = k1(x)
8498 >>> ax.plot(x, y)
8499 >>> plt.show()
8501 """)
8503add_newdoc("k1e",
8504 """
8505 k1e(x, out=None)
8507 Exponentially scaled modified Bessel function K of order 1
8509 Defined as::
8511 k1e(x) = exp(x) * k1(x)
8513 Parameters
8514 ----------
8515 x : array_like
8516 Argument (float)
8517 out : ndarray, optional
8518 Optional output array for the function values
8520 Returns
8521 -------
8522 K : scalar or ndarray
8523 Value of the exponentially scaled modified Bessel function K of order
8524 1 at `x`.
8526 Notes
8527 -----
8528 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8529 Chebyshev polynomial expansions are employed in each interval.
8531 This function is a wrapper for the Cephes [1]_ routine `k1e`.
8533 See also
8534 --------
8535 kv: Modified Bessel function of the second kind of any order
8536 k1: Modified Bessel function of the second kind of order 1
8538 References
8539 ----------
8540 .. [1] Cephes Mathematical Functions Library,
8541 http://www.netlib.org/cephes/
8543 Examples
8544 --------
8545 In the following example `k1` returns 0 whereas `k1e` still returns a
8546 useful floating point number.
8548 >>> from scipy.special import k1, k1e
8549 >>> k1(1000.), k1e(1000.)
8550 (0., 0.03964813081296021)
8552 Calculate the function at several points by providing a NumPy array or
8553 list for `x`:
8555 >>> import numpy as np
8556 >>> k1e(np.array([0.5, 2., 3.]))
8557 array([2.73100971, 1.03347685, 0.80656348])
8559 Plot the function from 0 to 10.
8561 >>> import matplotlib.pyplot as plt
8562 >>> fig, ax = plt.subplots()
8563 >>> x = np.linspace(0., 10., 1000)
8564 >>> y = k1e(x)
8565 >>> ax.plot(x, y)
8566 >>> plt.show()
8567 """)
8569add_newdoc("kei",
8570 r"""
8571 kei(x, out=None)
8573 Kelvin function kei.
8575 Defined as
8577 .. math::
8579 \mathrm{kei}(x) = \Im[K_0(x e^{\pi i / 4})]
8581 where :math:`K_0` is the modified Bessel function of the second
8582 kind (see `kv`). See [dlmf]_ for more details.
8584 Parameters
8585 ----------
8586 x : array_like
8587 Real argument.
8588 out : ndarray, optional
8589 Optional output array for the function results.
8591 Returns
8592 -------
8593 scalar or ndarray
8594 Values of the Kelvin function.
8596 See Also
8597 --------
8598 ker : the corresponding real part
8599 keip : the derivative of kei
8600 kv : modified Bessel function of the second kind
8602 References
8603 ----------
8604 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8605 https://dlmf.nist.gov/10.61
8607 Examples
8608 --------
8609 It can be expressed using the modified Bessel function of the
8610 second kind.
8612 >>> import numpy as np
8613 >>> import scipy.special as sc
8614 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
8615 >>> sc.kv(0, x * np.exp(np.pi * 1j / 4)).imag
8616 array([-0.49499464, -0.20240007, -0.05112188, 0.0021984 ])
8617 >>> sc.kei(x)
8618 array([-0.49499464, -0.20240007, -0.05112188, 0.0021984 ])
8620 """)
8622add_newdoc("keip",
8623 r"""
8624 keip(x, out=None)
8626 Derivative of the Kelvin function kei.
8628 Parameters
8629 ----------
8630 x : array_like
8631 Real argument.
8632 out : ndarray, optional
8633 Optional output array for the function results.
8635 Returns
8636 -------
8637 scalar or ndarray
8638 The values of the derivative of kei.
8640 See Also
8641 --------
8642 kei
8644 References
8645 ----------
8646 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8647 https://dlmf.nist.gov/10#PT5
8649 """)
8651add_newdoc("kelvin",
8652 """
8653 kelvin(x, out=None)
8655 Kelvin functions as complex numbers
8657 Parameters
8658 ----------
8659 x : array_like
8660 Argument
8661 out : tuple of ndarray, optional
8662 Optional output arrays for the function values
8664 Returns
8665 -------
8666 Be, Ke, Bep, Kep : 4-tuple of scalar or ndarray
8667 The tuple (Be, Ke, Bep, Kep) contains complex numbers
8668 representing the real and imaginary Kelvin functions and their
8669 derivatives evaluated at `x`. For example, kelvin(x)[0].real =
8670 ber x and kelvin(x)[0].imag = bei x with similar relationships
8671 for ker and kei.
8672 """)
8674add_newdoc("ker",
8675 r"""
8676 ker(x, out=None)
8678 Kelvin function ker.
8680 Defined as
8682 .. math::
8684 \mathrm{ker}(x) = \Re[K_0(x e^{\pi i / 4})]
8686 Where :math:`K_0` is the modified Bessel function of the second
8687 kind (see `kv`). See [dlmf]_ for more details.
8689 Parameters
8690 ----------
8691 x : array_like
8692 Real argument.
8693 out : ndarray, optional
8694 Optional output array for the function results.
8696 Returns
8697 -------
8698 scalar or ndarray
8699 Values of the Kelvin function.
8701 See Also
8702 --------
8703 kei : the corresponding imaginary part
8704 kerp : the derivative of ker
8705 kv : modified Bessel function of the second kind
8707 References
8708 ----------
8709 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8710 https://dlmf.nist.gov/10.61
8712 Examples
8713 --------
8714 It can be expressed using the modified Bessel function of the
8715 second kind.
8717 >>> import numpy as np
8718 >>> import scipy.special as sc
8719 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
8720 >>> sc.kv(0, x * np.exp(np.pi * 1j / 4)).real
8721 array([ 0.28670621, -0.04166451, -0.06702923, -0.03617885])
8722 >>> sc.ker(x)
8723 array([ 0.28670621, -0.04166451, -0.06702923, -0.03617885])
8725 """)
8727add_newdoc("kerp",
8728 r"""
8729 kerp(x, out=None)
8731 Derivative of the Kelvin function ker.
8733 Parameters
8734 ----------
8735 x : array_like
8736 Real argument.
8737 out : ndarray, optional
8738 Optional output array for the function results.
8740 Returns
8741 -------
8742 scalar or ndarray
8743 Values of the derivative of ker.
8745 See Also
8746 --------
8747 ker
8749 References
8750 ----------
8751 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8752 https://dlmf.nist.gov/10#PT5
8754 """)
8756add_newdoc("kl_div",
8757 r"""
8758 kl_div(x, y, out=None)
8760 Elementwise function for computing Kullback-Leibler divergence.
8762 .. math::
8764 \mathrm{kl\_div}(x, y) =
8765 \begin{cases}
8766 x \log(x / y) - x + y & x > 0, y > 0 \\
8767 y & x = 0, y \ge 0 \\
8768 \infty & \text{otherwise}
8769 \end{cases}
8771 Parameters
8772 ----------
8773 x, y : array_like
8774 Real arguments
8775 out : ndarray, optional
8776 Optional output array for the function results
8778 Returns
8779 -------
8780 scalar or ndarray
8781 Values of the Kullback-Liebler divergence.
8783 See Also
8784 --------
8785 entr, rel_entr, scipy.stats.entropy
8787 Notes
8788 -----
8789 .. versionadded:: 0.15.0
8791 This function is non-negative and is jointly convex in `x` and `y`.
8793 The origin of this function is in convex programming; see [1]_ for
8794 details. This is why the function contains the extra :math:`-x
8795 + y` terms over what might be expected from the Kullback-Leibler
8796 divergence. For a version of the function without the extra terms,
8797 see `rel_entr`.
8799 References
8800 ----------
8801 .. [1] Boyd, Stephen and Lieven Vandenberghe. *Convex optimization*.
8802 Cambridge University Press, 2004.
8803 :doi:`https://doi.org/10.1017/CBO9780511804441`
8805 """)
8807add_newdoc("kn",
8808 r"""
8809 kn(n, x, out=None)
8811 Modified Bessel function of the second kind of integer order `n`
8813 Returns the modified Bessel function of the second kind for integer order
8814 `n` at real `z`.
8816 These are also sometimes called functions of the third kind, Basset
8817 functions, or Macdonald functions.
8819 Parameters
8820 ----------
8821 n : array_like of int
8822 Order of Bessel functions (floats will truncate with a warning)
8823 x : array_like of float
8824 Argument at which to evaluate the Bessel functions
8825 out : ndarray, optional
8826 Optional output array for the function results.
8828 Returns
8829 -------
8830 scalar or ndarray
8831 Value of the Modified Bessel function of the second kind,
8832 :math:`K_n(x)`.
8834 Notes
8835 -----
8836 Wrapper for AMOS [1]_ routine `zbesk`. For a discussion of the
8837 algorithm used, see [2]_ and the references therein.
8839 See Also
8840 --------
8841 kv : Same function, but accepts real order and complex argument
8842 kvp : Derivative of this function
8844 References
8845 ----------
8846 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
8847 of a Complex Argument and Nonnegative Order",
8848 http://netlib.org/amos/
8849 .. [2] Donald E. Amos, "Algorithm 644: A portable package for Bessel
8850 functions of a complex argument and nonnegative order", ACM
8851 TOMS Vol. 12 Issue 3, Sept. 1986, p. 265
8853 Examples
8854 --------
8855 Plot the function of several orders for real input:
8857 >>> import numpy as np
8858 >>> from scipy.special import kn
8859 >>> import matplotlib.pyplot as plt
8860 >>> x = np.linspace(0, 5, 1000)
8861 >>> for N in range(6):
8862 ... plt.plot(x, kn(N, x), label='$K_{}(x)$'.format(N))
8863 >>> plt.ylim(0, 10)
8864 >>> plt.legend()
8865 >>> plt.title(r'Modified Bessel function of the second kind $K_n(x)$')
8866 >>> plt.show()
8868 Calculate for a single value at multiple orders:
8870 >>> kn([4, 5, 6], 1)
8871 array([ 44.23241585, 360.9605896 , 3653.83831186])
8872 """)
8874add_newdoc("kolmogi",
8875 """
8876 kolmogi(p, out=None)
8878 Inverse Survival Function of Kolmogorov distribution
8880 It is the inverse function to `kolmogorov`.
8881 Returns y such that ``kolmogorov(y) == p``.
8883 Parameters
8884 ----------
8885 p : float array_like
8886 Probability
8887 out : ndarray, optional
8888 Optional output array for the function results
8890 Returns
8891 -------
8892 scalar or ndarray
8893 The value(s) of kolmogi(p)
8895 Notes
8896 -----
8897 `kolmogorov` is used by `stats.kstest` in the application of the
8898 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
8899 function is exposed in `scpy.special`, but the recommended way to achieve
8900 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
8901 `stats.kstwobign` distribution.
8903 See Also
8904 --------
8905 kolmogorov : The Survival Function for the distribution
8906 scipy.stats.kstwobign : Provides the functionality as a continuous distribution
8907 smirnov, smirnovi : Functions for the one-sided distribution
8909 Examples
8910 --------
8911 >>> from scipy.special import kolmogi
8912 >>> kolmogi([0, 0.1, 0.25, 0.5, 0.75, 0.9, 1.0])
8913 array([ inf, 1.22384787, 1.01918472, 0.82757356, 0.67644769,
8914 0.57117327, 0. ])
8916 """)
8918add_newdoc("kolmogorov",
8919 r"""
8920 kolmogorov(y, out=None)
8922 Complementary cumulative distribution (Survival Function) function of
8923 Kolmogorov distribution.
8925 Returns the complementary cumulative distribution function of
8926 Kolmogorov's limiting distribution (``D_n*\sqrt(n)`` as n goes to infinity)
8927 of a two-sided test for equality between an empirical and a theoretical
8928 distribution. It is equal to the (limit as n->infinity of the)
8929 probability that ``sqrt(n) * max absolute deviation > y``.
8931 Parameters
8932 ----------
8933 y : float array_like
8934 Absolute deviation between the Empirical CDF (ECDF) and the target CDF,
8935 multiplied by sqrt(n).
8936 out : ndarray, optional
8937 Optional output array for the function results
8939 Returns
8940 -------
8941 scalar or ndarray
8942 The value(s) of kolmogorov(y)
8944 Notes
8945 -----
8946 `kolmogorov` is used by `stats.kstest` in the application of the
8947 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
8948 function is exposed in `scpy.special`, but the recommended way to achieve
8949 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
8950 `stats.kstwobign` distribution.
8952 See Also
8953 --------
8954 kolmogi : The Inverse Survival Function for the distribution
8955 scipy.stats.kstwobign : Provides the functionality as a continuous distribution
8956 smirnov, smirnovi : Functions for the one-sided distribution
8958 Examples
8959 --------
8960 Show the probability of a gap at least as big as 0, 0.5 and 1.0.
8962 >>> import numpy as np
8963 >>> from scipy.special import kolmogorov
8964 >>> from scipy.stats import kstwobign
8965 >>> kolmogorov([0, 0.5, 1.0])
8966 array([ 1. , 0.96394524, 0.26999967])
8968 Compare a sample of size 1000 drawn from a Laplace(0, 1) distribution against
8969 the target distribution, a Normal(0, 1) distribution.
8971 >>> from scipy.stats import norm, laplace
8972 >>> rng = np.random.default_rng()
8973 >>> n = 1000
8974 >>> lap01 = laplace(0, 1)
8975 >>> x = np.sort(lap01.rvs(n, random_state=rng))
8976 >>> np.mean(x), np.std(x)
8977 (-0.05841730131499543, 1.3968109101997568)
8979 Construct the Empirical CDF and the K-S statistic Dn.
8981 >>> target = norm(0,1) # Normal mean 0, stddev 1
8982 >>> cdfs = target.cdf(x)
8983 >>> ecdfs = np.arange(n+1, dtype=float)/n
8984 >>> gaps = np.column_stack([cdfs - ecdfs[:n], ecdfs[1:] - cdfs])
8985 >>> Dn = np.max(gaps)
8986 >>> Kn = np.sqrt(n) * Dn
8987 >>> print('Dn=%f, sqrt(n)*Dn=%f' % (Dn, Kn))
8988 Dn=0.043363, sqrt(n)*Dn=1.371265
8989 >>> print(chr(10).join(['For a sample of size n drawn from a N(0, 1) distribution:',
8990 ... ' the approximate Kolmogorov probability that sqrt(n)*Dn>=%f is %f' % (Kn, kolmogorov(Kn)),
8991 ... ' the approximate Kolmogorov probability that sqrt(n)*Dn<=%f is %f' % (Kn, kstwobign.cdf(Kn))]))
8992 For a sample of size n drawn from a N(0, 1) distribution:
8993 the approximate Kolmogorov probability that sqrt(n)*Dn>=1.371265 is 0.046533
8994 the approximate Kolmogorov probability that sqrt(n)*Dn<=1.371265 is 0.953467
8996 Plot the Empirical CDF against the target N(0, 1) CDF.
8998 >>> import matplotlib.pyplot as plt
8999 >>> plt.step(np.concatenate([[-3], x]), ecdfs, where='post', label='Empirical CDF')
9000 >>> x3 = np.linspace(-3, 3, 100)
9001 >>> plt.plot(x3, target.cdf(x3), label='CDF for N(0, 1)')
9002 >>> plt.ylim([0, 1]); plt.grid(True); plt.legend();
9003 >>> # Add vertical lines marking Dn+ and Dn-
9004 >>> iminus, iplus = np.argmax(gaps, axis=0)
9005 >>> plt.vlines([x[iminus]], ecdfs[iminus], cdfs[iminus], color='r', linestyle='dashed', lw=4)
9006 >>> plt.vlines([x[iplus]], cdfs[iplus], ecdfs[iplus+1], color='r', linestyle='dashed', lw=4)
9007 >>> plt.show()
9008 """)
9010add_newdoc("_kolmogc",
9011 r"""
9012 Internal function, do not use.
9013 """)
9015add_newdoc("_kolmogci",
9016 r"""
9017 Internal function, do not use.
9018 """)
9020add_newdoc("_kolmogp",
9021 r"""
9022 Internal function, do not use.
9023 """)
9025add_newdoc("kv",
9026 r"""
9027 kv(v, z, out=None)
9029 Modified Bessel function of the second kind of real order `v`
9031 Returns the modified Bessel function of the second kind for real order
9032 `v` at complex `z`.
9034 These are also sometimes called functions of the third kind, Basset
9035 functions, or Macdonald functions. They are defined as those solutions
9036 of the modified Bessel equation for which,
9038 .. math::
9039 K_v(x) \sim \sqrt{\pi/(2x)} \exp(-x)
9041 as :math:`x \to \infty` [3]_.
9043 Parameters
9044 ----------
9045 v : array_like of float
9046 Order of Bessel functions
9047 z : array_like of complex
9048 Argument at which to evaluate the Bessel functions
9049 out : ndarray, optional
9050 Optional output array for the function results
9052 Returns
9053 -------
9054 scalar or ndarray
9055 The results. Note that input must be of complex type to get complex
9056 output, e.g. ``kv(3, -2+0j)`` instead of ``kv(3, -2)``.
9058 Notes
9059 -----
9060 Wrapper for AMOS [1]_ routine `zbesk`. For a discussion of the
9061 algorithm used, see [2]_ and the references therein.
9063 See Also
9064 --------
9065 kve : This function with leading exponential behavior stripped off.
9066 kvp : Derivative of this function
9068 References
9069 ----------
9070 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
9071 of a Complex Argument and Nonnegative Order",
9072 http://netlib.org/amos/
9073 .. [2] Donald E. Amos, "Algorithm 644: A portable package for Bessel
9074 functions of a complex argument and nonnegative order", ACM
9075 TOMS Vol. 12 Issue 3, Sept. 1986, p. 265
9076 .. [3] NIST Digital Library of Mathematical Functions,
9077 Eq. 10.25.E3. https://dlmf.nist.gov/10.25.E3
9079 Examples
9080 --------
9081 Plot the function of several orders for real input:
9083 >>> import numpy as np
9084 >>> from scipy.special import kv
9085 >>> import matplotlib.pyplot as plt
9086 >>> x = np.linspace(0, 5, 1000)
9087 >>> for N in np.linspace(0, 6, 5):
9088 ... plt.plot(x, kv(N, x), label='$K_{{{}}}(x)$'.format(N))
9089 >>> plt.ylim(0, 10)
9090 >>> plt.legend()
9091 >>> plt.title(r'Modified Bessel function of the second kind $K_\nu(x)$')
9092 >>> plt.show()
9094 Calculate for a single value at multiple orders:
9096 >>> kv([4, 4.5, 5], 1+2j)
9097 array([ 0.1992+2.3892j, 2.3493+3.6j , 7.2827+3.8104j])
9099 """)
9101add_newdoc("kve",
9102 r"""
9103 kve(v, z, out=None)
9105 Exponentially scaled modified Bessel function of the second kind.
9107 Returns the exponentially scaled, modified Bessel function of the
9108 second kind (sometimes called the third kind) for real order `v` at
9109 complex `z`::
9111 kve(v, z) = kv(v, z) * exp(z)
9113 Parameters
9114 ----------
9115 v : array_like of float
9116 Order of Bessel functions
9117 z : array_like of complex
9118 Argument at which to evaluate the Bessel functions
9119 out : ndarray, optional
9120 Optional output array for the function results
9122 Returns
9123 -------
9124 scalar or ndarray
9125 The exponentially scaled modified Bessel function of the second kind.
9127 Notes
9128 -----
9129 Wrapper for AMOS [1]_ routine `zbesk`. For a discussion of the
9130 algorithm used, see [2]_ and the references therein.
9132 See Also
9133 --------
9134 kv : This function without exponential scaling.
9135 k0e : Faster version of this function for order 0.
9136 k1e : Faster version of this function for order 1.
9138 References
9139 ----------
9140 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
9141 of a Complex Argument and Nonnegative Order",
9142 http://netlib.org/amos/
9143 .. [2] Donald E. Amos, "Algorithm 644: A portable package for Bessel
9144 functions of a complex argument and nonnegative order", ACM
9145 TOMS Vol. 12 Issue 3, Sept. 1986, p. 265
9147 Examples
9148 --------
9149 In the following example `kv` returns 0 whereas `kve` still returns
9150 a useful finite number.
9152 >>> import numpy as np
9153 >>> from scipy.special import kv, kve
9154 >>> import matplotlib.pyplot as plt
9155 >>> kv(3, 1000.), kve(3, 1000.)
9156 (0.0, 0.03980696128440973)
9158 Evaluate the function at one point for different orders by
9159 providing a list or NumPy array as argument for the `v` parameter:
9161 >>> kve([0, 1, 1.5], 1.)
9162 array([1.14446308, 1.63615349, 2.50662827])
9164 Evaluate the function at several points for order 0 by providing an
9165 array for `z`.
9167 >>> points = np.array([1., 3., 10.])
9168 >>> kve(0, points)
9169 array([1.14446308, 0.6977616 , 0.39163193])
9171 Evaluate the function at several points for different orders by
9172 providing arrays for both `v` for `z`. Both arrays have to be
9173 broadcastable to the correct shape. To calculate the orders 0, 1
9174 and 2 for a 1D array of points:
9176 >>> kve([[0], [1], [2]], points)
9177 array([[1.14446308, 0.6977616 , 0.39163193],
9178 [1.63615349, 0.80656348, 0.41076657],
9179 [4.41677005, 1.23547058, 0.47378525]])
9181 Plot the functions of order 0 to 3 from 0 to 5.
9183 >>> fig, ax = plt.subplots()
9184 >>> x = np.linspace(0., 5., 1000)
9185 >>> for i in range(4):
9186 ... ax.plot(x, kve(i, x), label=f'$K_{i!r}(z)\cdot e^z$')
9187 >>> ax.legend()
9188 >>> ax.set_xlabel(r"$z$")
9189 >>> ax.set_ylim(0, 4)
9190 >>> ax.set_xlim(0, 5)
9191 >>> plt.show()
9192 """)
9194add_newdoc("_lanczos_sum_expg_scaled",
9195 """
9196 Internal function, do not use.
9197 """)
9199add_newdoc("_lgam1p",
9200 """
9201 Internal function, do not use.
9202 """)
9204add_newdoc("log1p",
9205 """
9206 log1p(x, out=None)
9208 Calculates log(1 + x) for use when `x` is near zero.
9210 Parameters
9211 ----------
9212 x : array_like
9213 Real or complex valued input.
9214 out : ndarray, optional
9215 Optional output array for the function results.
9217 Returns
9218 -------
9219 scalar or ndarray
9220 Values of ``log(1 + x)``.
9222 See Also
9223 --------
9224 expm1, cosm1
9226 Examples
9227 --------
9228 >>> import numpy as np
9229 >>> import scipy.special as sc
9231 It is more accurate than using ``log(1 + x)`` directly for ``x``
9232 near 0. Note that in the below example ``1 + 1e-17 == 1`` to
9233 double precision.
9235 >>> sc.log1p(1e-17)
9236 1e-17
9237 >>> np.log(1 + 1e-17)
9238 0.0
9240 """)
9242add_newdoc("_log1pmx",
9243 """
9244 Internal function, do not use.
9245 """)
9247add_newdoc('log_expit',
9248 """
9249 log_expit(x, out=None)
9251 Logarithm of the logistic sigmoid function.
9253 The SciPy implementation of the logistic sigmoid function is
9254 `scipy.special.expit`, so this function is called ``log_expit``.
9256 The function is mathematically equivalent to ``log(expit(x))``, but
9257 is formulated to avoid loss of precision for inputs with large
9258 (positive or negative) magnitude.
9260 Parameters
9261 ----------
9262 x : array_like
9263 The values to apply ``log_expit`` to element-wise.
9264 out : ndarray, optional
9265 Optional output array for the function results
9267 Returns
9268 -------
9269 out : scalar or ndarray
9270 The computed values, an ndarray of the same shape as ``x``.
9272 See Also
9273 --------
9274 expit
9276 Notes
9277 -----
9278 As a ufunc, ``log_expit`` takes a number of optional keyword arguments.
9279 For more information see
9280 `ufuncs <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`_
9282 .. versionadded:: 1.8.0
9284 Examples
9285 --------
9286 >>> import numpy as np
9287 >>> from scipy.special import log_expit, expit
9289 >>> log_expit([-3.0, 0.25, 2.5, 5.0])
9290 array([-3.04858735, -0.57593942, -0.07888973, -0.00671535])
9292 Large negative values:
9294 >>> log_expit([-100, -500, -1000])
9295 array([ -100., -500., -1000.])
9297 Note that ``expit(-1000)`` returns 0, so the naive implementation
9298 ``log(expit(-1000))`` return ``-inf``.
9300 Large positive values:
9302 >>> log_expit([29, 120, 400])
9303 array([-2.54366565e-013, -7.66764807e-053, -1.91516960e-174])
9305 Compare that to the naive implementation:
9307 >>> np.log(expit([29, 120, 400]))
9308 array([-2.54463117e-13, 0.00000000e+00, 0.00000000e+00])
9310 The first value is accurate to only 3 digits, and the larger inputs
9311 lose all precision and return 0.
9312 """)
9314add_newdoc('logit',
9315 """
9316 logit(x, out=None)
9318 Logit ufunc for ndarrays.
9320 The logit function is defined as logit(p) = log(p/(1-p)).
9321 Note that logit(0) = -inf, logit(1) = inf, and logit(p)
9322 for p<0 or p>1 yields nan.
9324 Parameters
9325 ----------
9326 x : ndarray
9327 The ndarray to apply logit to element-wise.
9328 out : ndarray, optional
9329 Optional output array for the function results
9331 Returns
9332 -------
9333 scalar or ndarray
9334 An ndarray of the same shape as x. Its entries
9335 are logit of the corresponding entry of x.
9337 See Also
9338 --------
9339 expit
9341 Notes
9342 -----
9343 As a ufunc logit takes a number of optional
9344 keyword arguments. For more information
9345 see `ufuncs <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`_
9347 .. versionadded:: 0.10.0
9349 Examples
9350 --------
9351 >>> import numpy as np
9352 >>> from scipy.special import logit, expit
9354 >>> logit([0, 0.25, 0.5, 0.75, 1])
9355 array([ -inf, -1.09861229, 0. , 1.09861229, inf])
9357 `expit` is the inverse of `logit`:
9359 >>> expit(logit([0.1, 0.75, 0.999]))
9360 array([ 0.1 , 0.75 , 0.999])
9362 Plot logit(x) for x in [0, 1]:
9364 >>> import matplotlib.pyplot as plt
9365 >>> x = np.linspace(0, 1, 501)
9366 >>> y = logit(x)
9367 >>> plt.plot(x, y)
9368 >>> plt.grid()
9369 >>> plt.ylim(-6, 6)
9370 >>> plt.xlabel('x')
9371 >>> plt.title('logit(x)')
9372 >>> plt.show()
9374 """)
9376add_newdoc("lpmv",
9377 r"""
9378 lpmv(m, v, x, out=None)
9380 Associated Legendre function of integer order and real degree.
9382 Defined as
9384 .. math::
9386 P_v^m = (-1)^m (1 - x^2)^{m/2} \frac{d^m}{dx^m} P_v(x)
9388 where
9390 .. math::
9392 P_v = \sum_{k = 0}^\infty \frac{(-v)_k (v + 1)_k}{(k!)^2}
9393 \left(\frac{1 - x}{2}\right)^k
9395 is the Legendre function of the first kind. Here :math:`(\cdot)_k`
9396 is the Pochhammer symbol; see `poch`.
9398 Parameters
9399 ----------
9400 m : array_like
9401 Order (int or float). If passed a float not equal to an
9402 integer the function returns NaN.
9403 v : array_like
9404 Degree (float).
9405 x : array_like
9406 Argument (float). Must have ``|x| <= 1``.
9407 out : ndarray, optional
9408 Optional output array for the function results
9410 Returns
9411 -------
9412 pmv : scalar or ndarray
9413 Value of the associated Legendre function.
9415 See Also
9416 --------
9417 lpmn : Compute the associated Legendre function for all orders
9418 ``0, ..., m`` and degrees ``0, ..., n``.
9419 clpmn : Compute the associated Legendre function at complex
9420 arguments.
9422 Notes
9423 -----
9424 Note that this implementation includes the Condon-Shortley phase.
9426 References
9427 ----------
9428 .. [1] Zhang, Jin, "Computation of Special Functions", John Wiley
9429 and Sons, Inc, 1996.
9431 """)
9433add_newdoc("mathieu_a",
9434 """
9435 mathieu_a(m, q, out=None)
9437 Characteristic value of even Mathieu functions
9439 Parameters
9440 ----------
9441 m : array_like
9442 Order of the function
9443 q : array_like
9444 Parameter of the function
9445 out : ndarray, optional
9446 Optional output array for the function results
9448 Returns
9449 -------
9450 scalar or ndarray
9451 Characteristic value for the even solution, ``ce_m(z, q)``, of
9452 Mathieu's equation.
9454 See Also
9455 --------
9456 mathieu_b, mathieu_cem, mathieu_sem
9458 """)
9460add_newdoc("mathieu_b",
9461 """
9462 mathieu_b(m, q, out=None)
9464 Characteristic value of odd Mathieu functions
9466 Parameters
9467 ----------
9468 m : array_like
9469 Order of the function
9470 q : array_like
9471 Parameter of the function
9472 out : ndarray, optional
9473 Optional output array for the function results
9475 Returns
9476 -------
9477 scalar or ndarray
9478 Characteristic value for the odd solution, ``se_m(z, q)``, of Mathieu's
9479 equation.
9481 See Also
9482 --------
9483 mathieu_a, mathieu_cem, mathieu_sem
9485 """)
9487add_newdoc("mathieu_cem",
9488 """
9489 mathieu_cem(m, q, x, out=None)
9491 Even Mathieu function and its derivative
9493 Returns the even Mathieu function, ``ce_m(x, q)``, of order `m` and
9494 parameter `q` evaluated at `x` (given in degrees). Also returns the
9495 derivative with respect to `x` of ce_m(x, q)
9497 Parameters
9498 ----------
9499 m : array_like
9500 Order of the function
9501 q : array_like
9502 Parameter of the function
9503 x : array_like
9504 Argument of the function, *given in degrees, not radians*
9505 out : tuple of ndarray, optional
9506 Optional output arrays for the function results
9508 Returns
9509 -------
9510 y : scalar or ndarray
9511 Value of the function
9512 yp : scalar or ndarray
9513 Value of the derivative vs x
9515 See Also
9516 --------
9517 mathieu_a, mathieu_b, mathieu_sem
9519 """)
9521add_newdoc("mathieu_modcem1",
9522 """
9523 mathieu_modcem1(m, q, x, out=None)
9525 Even modified Mathieu function of the first kind and its derivative
9527 Evaluates the even modified Mathieu function of the first kind,
9528 ``Mc1m(x, q)``, and its derivative at `x` for order `m` and parameter
9529 `q`.
9531 Parameters
9532 ----------
9533 m : array_like
9534 Order of the function
9535 q : array_like
9536 Parameter of the function
9537 x : array_like
9538 Argument of the function, *given in degrees, not radians*
9539 out : tuple of ndarray, optional
9540 Optional output arrays for the function results
9542 Returns
9543 -------
9544 y : scalar or ndarray
9545 Value of the function
9546 yp : scalar or ndarray
9547 Value of the derivative vs x
9549 See Also
9550 --------
9551 mathieu_modsem1
9553 """)
9555add_newdoc("mathieu_modcem2",
9556 """
9557 mathieu_modcem2(m, q, x, out=None)
9559 Even modified Mathieu function of the second kind and its derivative
9561 Evaluates the even modified Mathieu function of the second kind,
9562 Mc2m(x, q), and its derivative at `x` (given in degrees) for order `m`
9563 and parameter `q`.
9565 Parameters
9566 ----------
9567 m : array_like
9568 Order of the function
9569 q : array_like
9570 Parameter of the function
9571 x : array_like
9572 Argument of the function, *given in degrees, not radians*
9573 out : tuple of ndarray, optional
9574 Optional output arrays for the function results
9576 Returns
9577 -------
9578 y : scalar or ndarray
9579 Value of the function
9580 yp : scalar or ndarray
9581 Value of the derivative vs x
9583 See Also
9584 --------
9585 mathieu_modsem2
9587 """)
9589add_newdoc("mathieu_modsem1",
9590 """
9591 mathieu_modsem1(m, q, x, out=None)
9593 Odd modified Mathieu function of the first kind and its derivative
9595 Evaluates the odd modified Mathieu function of the first kind,
9596 Ms1m(x, q), and its derivative at `x` (given in degrees) for order `m`
9597 and parameter `q`.
9599 Parameters
9600 ----------
9601 m : array_like
9602 Order of the function
9603 q : array_like
9604 Parameter of the function
9605 x : array_like
9606 Argument of the function, *given in degrees, not radians*
9607 out : tuple of ndarray, optional
9608 Optional output arrays for the function results
9610 Returns
9611 -------
9612 y : scalar or ndarray
9613 Value of the function
9614 yp : scalar or ndarray
9615 Value of the derivative vs x
9617 See Also
9618 --------
9619 mathieu_modcem1
9621 """)
9623add_newdoc("mathieu_modsem2",
9624 """
9625 mathieu_modsem2(m, q, x, out=None)
9627 Odd modified Mathieu function of the second kind and its derivative
9629 Evaluates the odd modified Mathieu function of the second kind,
9630 Ms2m(x, q), and its derivative at `x` (given in degrees) for order `m`
9631 and parameter q.
9633 Parameters
9634 ----------
9635 m : array_like
9636 Order of the function
9637 q : array_like
9638 Parameter of the function
9639 x : array_like
9640 Argument of the function, *given in degrees, not radians*
9641 out : tuple of ndarray, optional
9642 Optional output arrays for the function results
9644 Returns
9645 -------
9646 y : scalar or ndarray
9647 Value of the function
9648 yp : scalar or ndarray
9649 Value of the derivative vs x
9651 See Also
9652 --------
9653 mathieu_modcem2
9655 """)
9657add_newdoc(
9658 "mathieu_sem",
9659 """
9660 mathieu_sem(m, q, x, out=None)
9662 Odd Mathieu function and its derivative
9664 Returns the odd Mathieu function, se_m(x, q), of order `m` and
9665 parameter `q` evaluated at `x` (given in degrees). Also returns the
9666 derivative with respect to `x` of se_m(x, q).
9668 Parameters
9669 ----------
9670 m : array_like
9671 Order of the function
9672 q : array_like
9673 Parameter of the function
9674 x : array_like
9675 Argument of the function, *given in degrees, not radians*.
9676 out : tuple of ndarray, optional
9677 Optional output arrays for the function results
9679 Returns
9680 -------
9681 y : scalar or ndarray
9682 Value of the function
9683 yp : scalar or ndarray
9684 Value of the derivative vs x
9686 See Also
9687 --------
9688 mathieu_a, mathieu_b, mathieu_cem
9690 """)
9692add_newdoc("modfresnelm",
9693 """
9694 modfresnelm(x, out=None)
9696 Modified Fresnel negative integrals
9698 Parameters
9699 ----------
9700 x : array_like
9701 Function argument
9702 out : tuple of ndarray, optional
9703 Optional output arrays for the function results
9705 Returns
9706 -------
9707 fm : scalar or ndarray
9708 Integral ``F_-(x)``: ``integral(exp(-1j*t*t), t=x..inf)``
9709 km : scalar or ndarray
9710 Integral ``K_-(x)``: ``1/sqrt(pi)*exp(1j*(x*x+pi/4))*fp``
9712 See Also
9713 --------
9714 modfresnelp
9716 """)
9718add_newdoc("modfresnelp",
9719 """
9720 modfresnelp(x, out=None)
9722 Modified Fresnel positive integrals
9724 Parameters
9725 ----------
9726 x : array_like
9727 Function argument
9728 out : tuple of ndarray, optional
9729 Optional output arrays for the function results
9731 Returns
9732 -------
9733 fp : scalar or ndarray
9734 Integral ``F_+(x)``: ``integral(exp(1j*t*t), t=x..inf)``
9735 kp : scalar or ndarray
9736 Integral ``K_+(x)``: ``1/sqrt(pi)*exp(-1j*(x*x+pi/4))*fp``
9738 See Also
9739 --------
9740 modfresnelm
9742 """)
9744add_newdoc("modstruve",
9745 r"""
9746 modstruve(v, x, out=None)
9748 Modified Struve function.
9750 Return the value of the modified Struve function of order `v` at `x`. The
9751 modified Struve function is defined as,
9753 .. math::
9754 L_v(x) = -\imath \exp(-\pi\imath v/2) H_v(\imath x),
9756 where :math:`H_v` is the Struve function.
9758 Parameters
9759 ----------
9760 v : array_like
9761 Order of the modified Struve function (float).
9762 x : array_like
9763 Argument of the Struve function (float; must be positive unless `v` is
9764 an integer).
9765 out : ndarray, optional
9766 Optional output array for the function results
9768 Returns
9769 -------
9770 L : scalar or ndarray
9771 Value of the modified Struve function of order `v` at `x`.
9773 Notes
9774 -----
9775 Three methods discussed in [1]_ are used to evaluate the function:
9777 - power series
9778 - expansion in Bessel functions (if :math:`|x| < |v| + 20`)
9779 - asymptotic large-x expansion (if :math:`x \geq 0.7v + 12`)
9781 Rounding errors are estimated based on the largest terms in the sums, and
9782 the result associated with the smallest error is returned.
9784 See also
9785 --------
9786 struve
9788 References
9789 ----------
9790 .. [1] NIST Digital Library of Mathematical Functions
9791 https://dlmf.nist.gov/11
9793 Examples
9794 --------
9795 Calculate the modified Struve function of order 1 at 2.
9797 >>> import numpy as np
9798 >>> from scipy.special import modstruve
9799 >>> import matplotlib.pyplot as plt
9800 >>> modstruve(1, 2.)
9801 1.102759787367716
9803 Calculate the modified Struve function at 2 for orders 1, 2 and 3 by
9804 providing a list for the order parameter `v`.
9806 >>> modstruve([1, 2, 3], 2.)
9807 array([1.10275979, 0.41026079, 0.11247294])
9809 Calculate the modified Struve function of order 1 for several points
9810 by providing an array for `x`.
9812 >>> points = np.array([2., 5., 8.])
9813 >>> modstruve(1, points)
9814 array([ 1.10275979, 23.72821578, 399.24709139])
9816 Compute the modified Struve function for several orders at several
9817 points by providing arrays for `v` and `z`. The arrays have to be
9818 broadcastable to the correct shapes.
9820 >>> orders = np.array([[1], [2], [3]])
9821 >>> points.shape, orders.shape
9822 ((3,), (3, 1))
9824 >>> modstruve(orders, points)
9825 array([[1.10275979e+00, 2.37282158e+01, 3.99247091e+02],
9826 [4.10260789e-01, 1.65535979e+01, 3.25973609e+02],
9827 [1.12472937e-01, 9.42430454e+00, 2.33544042e+02]])
9829 Plot the modified Struve functions of order 0 to 3 from -5 to 5.
9831 >>> fig, ax = plt.subplots()
9832 >>> x = np.linspace(-5., 5., 1000)
9833 >>> for i in range(4):
9834 ... ax.plot(x, modstruve(i, x), label=f'$L_{i!r}$')
9835 >>> ax.legend(ncol=2)
9836 >>> ax.set_xlim(-5, 5)
9837 >>> ax.set_title(r"Modified Struve functions $L_{\nu}$")
9838 >>> plt.show()
9839 """)
9841add_newdoc("nbdtr",
9842 r"""
9843 nbdtr(k, n, p, out=None)
9845 Negative binomial cumulative distribution function.
9847 Returns the sum of the terms 0 through `k` of the negative binomial
9848 distribution probability mass function,
9850 .. math::
9852 F = \sum_{j=0}^k {{n + j - 1}\choose{j}} p^n (1 - p)^j.
9854 In a sequence of Bernoulli trials with individual success probabilities
9855 `p`, this is the probability that `k` or fewer failures precede the nth
9856 success.
9858 Parameters
9859 ----------
9860 k : array_like
9861 The maximum number of allowed failures (nonnegative int).
9862 n : array_like
9863 The target number of successes (positive int).
9864 p : array_like
9865 Probability of success in a single event (float).
9866 out : ndarray, optional
9867 Optional output array for the function results
9869 Returns
9870 -------
9871 F : scalar or ndarray
9872 The probability of `k` or fewer failures before `n` successes in a
9873 sequence of events with individual success probability `p`.
9875 See also
9876 --------
9877 nbdtrc : Negative binomial survival function
9878 nbdtrik : Negative binomial quantile function
9879 scipy.stats.nbinom : Negative binomial distribution
9881 Notes
9882 -----
9883 If floating point values are passed for `k` or `n`, they will be truncated
9884 to integers.
9886 The terms are not summed directly; instead the regularized incomplete beta
9887 function is employed, according to the formula,
9889 .. math::
9890 \mathrm{nbdtr}(k, n, p) = I_{p}(n, k + 1).
9892 Wrapper for the Cephes [1]_ routine `nbdtr`.
9894 The negative binomial distribution is also available as
9895 `scipy.stats.nbinom`. Using `nbdtr` directly can improve performance
9896 compared to the ``cdf`` method of `scipy.stats.nbinom` (see last example).
9898 References
9899 ----------
9900 .. [1] Cephes Mathematical Functions Library,
9901 http://www.netlib.org/cephes/
9903 Examples
9904 --------
9905 Compute the function for ``k=10`` and ``n=5`` at ``p=0.5``.
9907 >>> import numpy as np
9908 >>> from scipy.special import nbdtr
9909 >>> nbdtr(10, 5, 0.5)
9910 0.940765380859375
9912 Compute the function for ``n=10`` and ``p=0.5`` at several points by
9913 providing a NumPy array or list for `k`.
9915 >>> nbdtr([5, 10, 15], 10, 0.5)
9916 array([0.15087891, 0.58809853, 0.88523853])
9918 Plot the function for four different parameter sets.
9920 >>> import matplotlib.pyplot as plt
9921 >>> k = np.arange(130)
9922 >>> n_parameters = [20, 20, 20, 80]
9923 >>> p_parameters = [0.2, 0.5, 0.8, 0.5]
9924 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
9925 >>> parameters_list = list(zip(p_parameters, n_parameters,
9926 ... linestyles))
9927 >>> fig, ax = plt.subplots(figsize=(8, 8))
9928 >>> for parameter_set in parameters_list:
9929 ... p, n, style = parameter_set
9930 ... nbdtr_vals = nbdtr(k, n, p)
9931 ... ax.plot(k, nbdtr_vals, label=rf"$n={n},\, p={p}$",
9932 ... ls=style)
9933 >>> ax.legend()
9934 >>> ax.set_xlabel("$k$")
9935 >>> ax.set_title("Negative binomial cumulative distribution function")
9936 >>> plt.show()
9938 The negative binomial distribution is also available as
9939 `scipy.stats.nbinom`. Using `nbdtr` directly can be much faster than
9940 calling the ``cdf`` method of `scipy.stats.nbinom`, especially for small
9941 arrays or individual values. To get the same results one must use the
9942 following parametrization: ``nbinom(n, p).cdf(k)=nbdtr(k, n, p)``.
9944 >>> from scipy.stats import nbinom
9945 >>> k, n, p = 5, 3, 0.5
9946 >>> nbdtr_res = nbdtr(k, n, p) # this will often be faster than below
9947 >>> stats_res = nbinom(n, p).cdf(k)
9948 >>> stats_res, nbdtr_res # test that results are equal
9949 (0.85546875, 0.85546875)
9951 `nbdtr` can evaluate different parameter sets by providing arrays with
9952 shapes compatible for broadcasting for `k`, `n` and `p`. Here we compute
9953 the function for three different `k` at four locations `p`, resulting in
9954 a 3x4 array.
9956 >>> k = np.array([[5], [10], [15]])
9957 >>> p = np.array([0.3, 0.5, 0.7, 0.9])
9958 >>> k.shape, p.shape
9959 ((3, 1), (4,))
9961 >>> nbdtr(k, 5, p)
9962 array([[0.15026833, 0.62304687, 0.95265101, 0.9998531 ],
9963 [0.48450894, 0.94076538, 0.99932777, 0.99999999],
9964 [0.76249222, 0.99409103, 0.99999445, 1. ]])
9965 """)
9967add_newdoc("nbdtrc",
9968 r"""
9969 nbdtrc(k, n, p, out=None)
9971 Negative binomial survival function.
9973 Returns the sum of the terms `k + 1` to infinity of the negative binomial
9974 distribution probability mass function,
9976 .. math::
9978 F = \sum_{j=k + 1}^\infty {{n + j - 1}\choose{j}} p^n (1 - p)^j.
9980 In a sequence of Bernoulli trials with individual success probabilities
9981 `p`, this is the probability that more than `k` failures precede the nth
9982 success.
9984 Parameters
9985 ----------
9986 k : array_like
9987 The maximum number of allowed failures (nonnegative int).
9988 n : array_like
9989 The target number of successes (positive int).
9990 p : array_like
9991 Probability of success in a single event (float).
9992 out : ndarray, optional
9993 Optional output array for the function results
9995 Returns
9996 -------
9997 F : scalar or ndarray
9998 The probability of `k + 1` or more failures before `n` successes in a
9999 sequence of events with individual success probability `p`.
10001 See also
10002 --------
10003 nbdtr : Negative binomial cumulative distribution function
10004 nbdtrik : Negative binomial percentile function
10005 scipy.stats.nbinom : Negative binomial distribution
10007 Notes
10008 -----
10009 If floating point values are passed for `k` or `n`, they will be truncated
10010 to integers.
10012 The terms are not summed directly; instead the regularized incomplete beta
10013 function is employed, according to the formula,
10015 .. math::
10016 \mathrm{nbdtrc}(k, n, p) = I_{1 - p}(k + 1, n).
10018 Wrapper for the Cephes [1]_ routine `nbdtrc`.
10020 The negative binomial distribution is also available as
10021 `scipy.stats.nbinom`. Using `nbdtrc` directly can improve performance
10022 compared to the ``sf`` method of `scipy.stats.nbinom` (see last example).
10024 References
10025 ----------
10026 .. [1] Cephes Mathematical Functions Library,
10027 http://www.netlib.org/cephes/
10029 Examples
10030 --------
10031 Compute the function for ``k=10`` and ``n=5`` at ``p=0.5``.
10033 >>> import numpy as np
10034 >>> from scipy.special import nbdtrc
10035 >>> nbdtrc(10, 5, 0.5)
10036 0.059234619140624986
10038 Compute the function for ``n=10`` and ``p=0.5`` at several points by
10039 providing a NumPy array or list for `k`.
10041 >>> nbdtrc([5, 10, 15], 10, 0.5)
10042 array([0.84912109, 0.41190147, 0.11476147])
10044 Plot the function for four different parameter sets.
10046 >>> import matplotlib.pyplot as plt
10047 >>> k = np.arange(130)
10048 >>> n_parameters = [20, 20, 20, 80]
10049 >>> p_parameters = [0.2, 0.5, 0.8, 0.5]
10050 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
10051 >>> parameters_list = list(zip(p_parameters, n_parameters,
10052 ... linestyles))
10053 >>> fig, ax = plt.subplots(figsize=(8, 8))
10054 >>> for parameter_set in parameters_list:
10055 ... p, n, style = parameter_set
10056 ... nbdtrc_vals = nbdtrc(k, n, p)
10057 ... ax.plot(k, nbdtrc_vals, label=rf"$n={n},\, p={p}$",
10058 ... ls=style)
10059 >>> ax.legend()
10060 >>> ax.set_xlabel("$k$")
10061 >>> ax.set_title("Negative binomial distribution survival function")
10062 >>> plt.show()
10064 The negative binomial distribution is also available as
10065 `scipy.stats.nbinom`. Using `nbdtrc` directly can be much faster than
10066 calling the ``sf`` method of `scipy.stats.nbinom`, especially for small
10067 arrays or individual values. To get the same results one must use the
10068 following parametrization: ``nbinom(n, p).sf(k)=nbdtrc(k, n, p)``.
10070 >>> from scipy.stats import nbinom
10071 >>> k, n, p = 3, 5, 0.5
10072 >>> nbdtr_res = nbdtrc(k, n, p) # this will often be faster than below
10073 >>> stats_res = nbinom(n, p).sf(k)
10074 >>> stats_res, nbdtr_res # test that results are equal
10075 (0.6367187499999999, 0.6367187499999999)
10077 `nbdtrc` can evaluate different parameter sets by providing arrays with
10078 shapes compatible for broadcasting for `k`, `n` and `p`. Here we compute
10079 the function for three different `k` at four locations `p`, resulting in
10080 a 3x4 array.
10082 >>> k = np.array([[5], [10], [15]])
10083 >>> p = np.array([0.3, 0.5, 0.7, 0.9])
10084 >>> k.shape, p.shape
10085 ((3, 1), (4,))
10087 >>> nbdtrc(k, 5, p)
10088 array([[8.49731667e-01, 3.76953125e-01, 4.73489874e-02, 1.46902600e-04],
10089 [5.15491059e-01, 5.92346191e-02, 6.72234070e-04, 9.29610100e-09],
10090 [2.37507779e-01, 5.90896606e-03, 5.55025308e-06, 3.26346760e-13]])
10091 """)
10093add_newdoc(
10094 "nbdtri",
10095 r"""
10096 nbdtri(k, n, y, out=None)
10098 Returns the inverse with respect to the parameter `p` of
10099 `y = nbdtr(k, n, p)`, the negative binomial cumulative distribution
10100 function.
10102 Parameters
10103 ----------
10104 k : array_like
10105 The maximum number of allowed failures (nonnegative int).
10106 n : array_like
10107 The target number of successes (positive int).
10108 y : array_like
10109 The probability of `k` or fewer failures before `n` successes (float).
10110 out : ndarray, optional
10111 Optional output array for the function results
10113 Returns
10114 -------
10115 p : scalar or ndarray
10116 Probability of success in a single event (float) such that
10117 `nbdtr(k, n, p) = y`.
10119 See also
10120 --------
10121 nbdtr : Cumulative distribution function of the negative binomial.
10122 nbdtrc : Negative binomial survival function.
10123 scipy.stats.nbinom : negative binomial distribution.
10124 nbdtrik : Inverse with respect to `k` of `nbdtr(k, n, p)`.
10125 nbdtrin : Inverse with respect to `n` of `nbdtr(k, n, p)`.
10126 scipy.stats.nbinom : Negative binomial distribution
10128 Notes
10129 -----
10130 Wrapper for the Cephes [1]_ routine `nbdtri`.
10132 The negative binomial distribution is also available as
10133 `scipy.stats.nbinom`. Using `nbdtri` directly can improve performance
10134 compared to the ``ppf`` method of `scipy.stats.nbinom`.
10136 References
10137 ----------
10138 .. [1] Cephes Mathematical Functions Library,
10139 http://www.netlib.org/cephes/
10141 Examples
10142 --------
10143 `nbdtri` is the inverse of `nbdtr` with respect to `p`.
10144 Up to floating point errors the following holds:
10145 ``nbdtri(k, n, nbdtr(k, n, p))=p``.
10147 >>> import numpy as np
10148 >>> from scipy.special import nbdtri, nbdtr
10149 >>> k, n, y = 5, 10, 0.2
10150 >>> cdf_val = nbdtr(k, n, y)
10151 >>> nbdtri(k, n, cdf_val)
10152 0.20000000000000004
10154 Compute the function for ``k=10`` and ``n=5`` at several points by
10155 providing a NumPy array or list for `y`.
10157 >>> y = np.array([0.1, 0.4, 0.8])
10158 >>> nbdtri(3, 5, y)
10159 array([0.34462319, 0.51653095, 0.69677416])
10161 Plot the function for three different parameter sets.
10163 >>> import matplotlib.pyplot as plt
10164 >>> n_parameters = [5, 20, 30, 30]
10165 >>> k_parameters = [20, 20, 60, 80]
10166 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
10167 >>> parameters_list = list(zip(n_parameters, k_parameters, linestyles))
10168 >>> cdf_vals = np.linspace(0, 1, 1000)
10169 >>> fig, ax = plt.subplots(figsize=(8, 8))
10170 >>> for parameter_set in parameters_list:
10171 ... n, k, style = parameter_set
10172 ... nbdtri_vals = nbdtri(k, n, cdf_vals)
10173 ... ax.plot(cdf_vals, nbdtri_vals, label=rf"$k={k},\ n={n}$",
10174 ... ls=style)
10175 >>> ax.legend()
10176 >>> ax.set_ylabel("$p$")
10177 >>> ax.set_xlabel("$CDF$")
10178 >>> title = "nbdtri: inverse of negative binomial CDF with respect to $p$"
10179 >>> ax.set_title(title)
10180 >>> plt.show()
10182 `nbdtri` can evaluate different parameter sets by providing arrays with
10183 shapes compatible for broadcasting for `k`, `n` and `p`. Here we compute
10184 the function for three different `k` at four locations `p`, resulting in
10185 a 3x4 array.
10187 >>> k = np.array([[5], [10], [15]])
10188 >>> y = np.array([0.3, 0.5, 0.7, 0.9])
10189 >>> k.shape, y.shape
10190 ((3, 1), (4,))
10192 >>> nbdtri(k, 5, y)
10193 array([[0.37258157, 0.45169416, 0.53249956, 0.64578407],
10194 [0.24588501, 0.30451981, 0.36778453, 0.46397088],
10195 [0.18362101, 0.22966758, 0.28054743, 0.36066188]])
10196 """)
10198add_newdoc("nbdtrik",
10199 r"""
10200 nbdtrik(y, n, p, out=None)
10202 Negative binomial percentile function.
10204 Returns the inverse with respect to the parameter `k` of
10205 `y = nbdtr(k, n, p)`, the negative binomial cumulative distribution
10206 function.
10208 Parameters
10209 ----------
10210 y : array_like
10211 The probability of `k` or fewer failures before `n` successes (float).
10212 n : array_like
10213 The target number of successes (positive int).
10214 p : array_like
10215 Probability of success in a single event (float).
10216 out : ndarray, optional
10217 Optional output array for the function results
10219 Returns
10220 -------
10221 k : scalar or ndarray
10222 The maximum number of allowed failures such that `nbdtr(k, n, p) = y`.
10224 See also
10225 --------
10226 nbdtr : Cumulative distribution function of the negative binomial.
10227 nbdtrc : Survival function of the negative binomial.
10228 nbdtri : Inverse with respect to `p` of `nbdtr(k, n, p)`.
10229 nbdtrin : Inverse with respect to `n` of `nbdtr(k, n, p)`.
10230 scipy.stats.nbinom : Negative binomial distribution
10232 Notes
10233 -----
10234 Wrapper for the CDFLIB [1]_ Fortran routine `cdfnbn`.
10236 Formula 26.5.26 of [2]_,
10238 .. math::
10239 \sum_{j=k + 1}^\infty {{n + j - 1}\choose{j}} p^n (1 - p)^j = I_{1 - p}(k + 1, n),
10241 is used to reduce calculation of the cumulative distribution function to
10242 that of a regularized incomplete beta :math:`I`.
10244 Computation of `k` involves a search for a value that produces the desired
10245 value of `y`. The search relies on the monotonicity of `y` with `k`.
10247 References
10248 ----------
10249 .. [1] Barry Brown, James Lovato, and Kathy Russell,
10250 CDFLIB: Library of Fortran Routines for Cumulative Distribution
10251 Functions, Inverses, and Other Parameters.
10252 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
10253 Handbook of Mathematical Functions with Formulas,
10254 Graphs, and Mathematical Tables. New York: Dover, 1972.
10256 Examples
10257 --------
10258 Compute the negative binomial cumulative distribution function for an
10259 exemplary parameter set.
10261 >>> import numpy as np
10262 >>> from scipy.special import nbdtr, nbdtrik
10263 >>> k, n, p = 5, 2, 0.5
10264 >>> cdf_value = nbdtr(k, n, p)
10265 >>> cdf_value
10266 0.9375
10268 Verify that `nbdtrik` recovers the original value for `k`.
10270 >>> nbdtrik(cdf_value, n, p)
10271 5.0
10273 Plot the function for different parameter sets.
10275 >>> import matplotlib.pyplot as plt
10276 >>> p_parameters = [0.2, 0.5, 0.7, 0.5]
10277 >>> n_parameters = [30, 30, 30, 80]
10278 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
10279 >>> parameters_list = list(zip(p_parameters, n_parameters, linestyles))
10280 >>> cdf_vals = np.linspace(0, 1, 1000)
10281 >>> fig, ax = plt.subplots(figsize=(8, 8))
10282 >>> for parameter_set in parameters_list:
10283 ... p, n, style = parameter_set
10284 ... nbdtrik_vals = nbdtrik(cdf_vals, n, p)
10285 ... ax.plot(cdf_vals, nbdtrik_vals, label=rf"$n={n},\ p={p}$",
10286 ... ls=style)
10287 >>> ax.legend()
10288 >>> ax.set_ylabel("$k$")
10289 >>> ax.set_xlabel("$CDF$")
10290 >>> ax.set_title("Negative binomial percentile function")
10291 >>> plt.show()
10293 The negative binomial distribution is also available as
10294 `scipy.stats.nbinom`. The percentile function method ``ppf``
10295 returns the result of `nbdtrik` rounded up to integers:
10297 >>> from scipy.stats import nbinom
10298 >>> q, n, p = 0.6, 5, 0.5
10299 >>> nbinom.ppf(q, n, p), nbdtrik(q, n, p)
10300 (5.0, 4.800428460273882)
10302 """)
10304add_newdoc("nbdtrin",
10305 r"""
10306 nbdtrin(k, y, p, out=None)
10308 Inverse of `nbdtr` vs `n`.
10310 Returns the inverse with respect to the parameter `n` of
10311 `y = nbdtr(k, n, p)`, the negative binomial cumulative distribution
10312 function.
10314 Parameters
10315 ----------
10316 k : array_like
10317 The maximum number of allowed failures (nonnegative int).
10318 y : array_like
10319 The probability of `k` or fewer failures before `n` successes (float).
10320 p : array_like
10321 Probability of success in a single event (float).
10322 out : ndarray, optional
10323 Optional output array for the function results
10325 Returns
10326 -------
10327 n : scalar or ndarray
10328 The number of successes `n` such that `nbdtr(k, n, p) = y`.
10330 See also
10331 --------
10332 nbdtr : Cumulative distribution function of the negative binomial.
10333 nbdtri : Inverse with respect to `p` of `nbdtr(k, n, p)`.
10334 nbdtrik : Inverse with respect to `k` of `nbdtr(k, n, p)`.
10336 Notes
10337 -----
10338 Wrapper for the CDFLIB [1]_ Fortran routine `cdfnbn`.
10340 Formula 26.5.26 of [2]_,
10342 .. math::
10343 \sum_{j=k + 1}^\infty {{n + j - 1}\choose{j}} p^n (1 - p)^j = I_{1 - p}(k + 1, n),
10345 is used to reduce calculation of the cumulative distribution function to
10346 that of a regularized incomplete beta :math:`I`.
10348 Computation of `n` involves a search for a value that produces the desired
10349 value of `y`. The search relies on the monotonicity of `y` with `n`.
10351 References
10352 ----------
10353 .. [1] Barry Brown, James Lovato, and Kathy Russell,
10354 CDFLIB: Library of Fortran Routines for Cumulative Distribution
10355 Functions, Inverses, and Other Parameters.
10356 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
10357 Handbook of Mathematical Functions with Formulas,
10358 Graphs, and Mathematical Tables. New York: Dover, 1972.
10360 Examples
10361 --------
10362 Compute the negative binomial cumulative distribution function for an
10363 exemplary parameter set.
10365 >>> from scipy.special import nbdtr, nbdtrin
10366 >>> k, n, p = 5, 2, 0.5
10367 >>> cdf_value = nbdtr(k, n, p)
10368 >>> cdf_value
10369 0.9375
10371 Verify that `nbdtrin` recovers the original value for `n` up to floating
10372 point accuracy.
10374 >>> nbdtrin(k, cdf_value, p)
10375 1.999999999998137
10376 """)
10378add_newdoc("ncfdtr",
10379 r"""
10380 ncfdtr(dfn, dfd, nc, f, out=None)
10382 Cumulative distribution function of the non-central F distribution.
10384 The non-central F describes the distribution of,
10386 .. math::
10387 Z = \frac{X/d_n}{Y/d_d}
10389 where :math:`X` and :math:`Y` are independently distributed, with
10390 :math:`X` distributed non-central :math:`\chi^2` with noncentrality
10391 parameter `nc` and :math:`d_n` degrees of freedom, and :math:`Y`
10392 distributed :math:`\chi^2` with :math:`d_d` degrees of freedom.
10394 Parameters
10395 ----------
10396 dfn : array_like
10397 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10398 dfd : array_like
10399 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10400 nc : array_like
10401 Noncentrality parameter. Should be in range (0, 1e4).
10402 f : array_like
10403 Quantiles, i.e. the upper limit of integration.
10404 out : ndarray, optional
10405 Optional output array for the function results
10407 Returns
10408 -------
10409 cdf : scalar or ndarray
10410 The calculated CDF. If all inputs are scalar, the return will be a
10411 float. Otherwise it will be an array.
10413 See Also
10414 --------
10415 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10416 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10417 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10418 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10420 Notes
10421 -----
10422 Wrapper for the CDFLIB [1]_ Fortran routine `cdffnc`.
10424 The cumulative distribution function is computed using Formula 26.6.20 of
10425 [2]_:
10427 .. math::
10428 F(d_n, d_d, n_c, f) = \sum_{j=0}^\infty e^{-n_c/2} \frac{(n_c/2)^j}{j!} I_{x}(\frac{d_n}{2} + j, \frac{d_d}{2}),
10430 where :math:`I` is the regularized incomplete beta function, and
10431 :math:`x = f d_n/(f d_n + d_d)`.
10433 The computation time required for this routine is proportional to the
10434 noncentrality parameter `nc`. Very large values of this parameter can
10435 consume immense computer resources. This is why the search range is
10436 bounded by 10,000.
10438 References
10439 ----------
10440 .. [1] Barry Brown, James Lovato, and Kathy Russell,
10441 CDFLIB: Library of Fortran Routines for Cumulative Distribution
10442 Functions, Inverses, and Other Parameters.
10443 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
10444 Handbook of Mathematical Functions with Formulas,
10445 Graphs, and Mathematical Tables. New York: Dover, 1972.
10447 Examples
10448 --------
10449 >>> import numpy as np
10450 >>> from scipy import special
10451 >>> from scipy import stats
10452 >>> import matplotlib.pyplot as plt
10454 Plot the CDF of the non-central F distribution, for nc=0. Compare with the
10455 F-distribution from scipy.stats:
10457 >>> x = np.linspace(-1, 8, num=500)
10458 >>> dfn = 3
10459 >>> dfd = 2
10460 >>> ncf_stats = stats.f.cdf(x, dfn, dfd)
10461 >>> ncf_special = special.ncfdtr(dfn, dfd, 0, x)
10463 >>> fig = plt.figure()
10464 >>> ax = fig.add_subplot(111)
10465 >>> ax.plot(x, ncf_stats, 'b-', lw=3)
10466 >>> ax.plot(x, ncf_special, 'r-')
10467 >>> plt.show()
10469 """)
10471add_newdoc("ncfdtri",
10472 """
10473 ncfdtri(dfn, dfd, nc, p, out=None)
10475 Inverse with respect to `f` of the CDF of the non-central F distribution.
10477 See `ncfdtr` for more details.
10479 Parameters
10480 ----------
10481 dfn : array_like
10482 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10483 dfd : array_like
10484 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10485 nc : array_like
10486 Noncentrality parameter. Should be in range (0, 1e4).
10487 p : array_like
10488 Value of the cumulative distribution function. Must be in the
10489 range [0, 1].
10490 out : ndarray, optional
10491 Optional output array for the function results
10493 Returns
10494 -------
10495 f : scalar or ndarray
10496 Quantiles, i.e., the upper limit of integration.
10498 See Also
10499 --------
10500 ncfdtr : CDF of the non-central F distribution.
10501 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10502 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10503 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10505 Examples
10506 --------
10507 >>> from scipy.special import ncfdtr, ncfdtri
10509 Compute the CDF for several values of `f`:
10511 >>> f = [0.5, 1, 1.5]
10512 >>> p = ncfdtr(2, 3, 1.5, f)
10513 >>> p
10514 array([ 0.20782291, 0.36107392, 0.47345752])
10516 Compute the inverse. We recover the values of `f`, as expected:
10518 >>> ncfdtri(2, 3, 1.5, p)
10519 array([ 0.5, 1. , 1.5])
10521 """)
10523add_newdoc("ncfdtridfd",
10524 """
10525 ncfdtridfd(dfn, p, nc, f, out=None)
10527 Calculate degrees of freedom (denominator) for the noncentral F-distribution.
10529 This is the inverse with respect to `dfd` of `ncfdtr`.
10530 See `ncfdtr` for more details.
10532 Parameters
10533 ----------
10534 dfn : array_like
10535 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10536 p : array_like
10537 Value of the cumulative distribution function. Must be in the
10538 range [0, 1].
10539 nc : array_like
10540 Noncentrality parameter. Should be in range (0, 1e4).
10541 f : array_like
10542 Quantiles, i.e., the upper limit of integration.
10543 out : ndarray, optional
10544 Optional output array for the function results
10546 Returns
10547 -------
10548 dfd : scalar or ndarray
10549 Degrees of freedom of the denominator sum of squares.
10551 See Also
10552 --------
10553 ncfdtr : CDF of the non-central F distribution.
10554 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10555 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10556 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10558 Notes
10559 -----
10560 The value of the cumulative noncentral F distribution is not necessarily
10561 monotone in either degrees of freedom. There thus may be two values that
10562 provide a given CDF value. This routine assumes monotonicity and will
10563 find an arbitrary one of the two values.
10565 Examples
10566 --------
10567 >>> from scipy.special import ncfdtr, ncfdtridfd
10569 Compute the CDF for several values of `dfd`:
10571 >>> dfd = [1, 2, 3]
10572 >>> p = ncfdtr(2, dfd, 0.25, 15)
10573 >>> p
10574 array([ 0.8097138 , 0.93020416, 0.96787852])
10576 Compute the inverse. We recover the values of `dfd`, as expected:
10578 >>> ncfdtridfd(2, p, 0.25, 15)
10579 array([ 1., 2., 3.])
10581 """)
10583add_newdoc("ncfdtridfn",
10584 """
10585 ncfdtridfn(p, dfd, nc, f, out=None)
10587 Calculate degrees of freedom (numerator) for the noncentral F-distribution.
10589 This is the inverse with respect to `dfn` of `ncfdtr`.
10590 See `ncfdtr` for more details.
10592 Parameters
10593 ----------
10594 p : array_like
10595 Value of the cumulative distribution function. Must be in the
10596 range [0, 1].
10597 dfd : array_like
10598 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10599 nc : array_like
10600 Noncentrality parameter. Should be in range (0, 1e4).
10601 f : float
10602 Quantiles, i.e., the upper limit of integration.
10603 out : ndarray, optional
10604 Optional output array for the function results
10606 Returns
10607 -------
10608 dfn : scalar or ndarray
10609 Degrees of freedom of the numerator sum of squares.
10611 See Also
10612 --------
10613 ncfdtr : CDF of the non-central F distribution.
10614 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10615 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10616 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10618 Notes
10619 -----
10620 The value of the cumulative noncentral F distribution is not necessarily
10621 monotone in either degrees of freedom. There thus may be two values that
10622 provide a given CDF value. This routine assumes monotonicity and will
10623 find an arbitrary one of the two values.
10625 Examples
10626 --------
10627 >>> from scipy.special import ncfdtr, ncfdtridfn
10629 Compute the CDF for several values of `dfn`:
10631 >>> dfn = [1, 2, 3]
10632 >>> p = ncfdtr(dfn, 2, 0.25, 15)
10633 >>> p
10634 array([ 0.92562363, 0.93020416, 0.93188394])
10636 Compute the inverse. We recover the values of `dfn`, as expected:
10638 >>> ncfdtridfn(p, 2, 0.25, 15)
10639 array([ 1., 2., 3.])
10641 """)
10643add_newdoc("ncfdtrinc",
10644 """
10645 ncfdtrinc(dfn, dfd, p, f, out=None)
10647 Calculate non-centrality parameter for non-central F distribution.
10649 This is the inverse with respect to `nc` of `ncfdtr`.
10650 See `ncfdtr` for more details.
10652 Parameters
10653 ----------
10654 dfn : array_like
10655 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10656 dfd : array_like
10657 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10658 p : array_like
10659 Value of the cumulative distribution function. Must be in the
10660 range [0, 1].
10661 f : array_like
10662 Quantiles, i.e., the upper limit of integration.
10663 out : ndarray, optional
10664 Optional output array for the function results
10666 Returns
10667 -------
10668 nc : scalar or ndarray
10669 Noncentrality parameter.
10671 See Also
10672 --------
10673 ncfdtr : CDF of the non-central F distribution.
10674 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10675 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10676 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10678 Examples
10679 --------
10680 >>> from scipy.special import ncfdtr, ncfdtrinc
10682 Compute the CDF for several values of `nc`:
10684 >>> nc = [0.5, 1.5, 2.0]
10685 >>> p = ncfdtr(2, 3, nc, 15)
10686 >>> p
10687 array([ 0.96309246, 0.94327955, 0.93304098])
10689 Compute the inverse. We recover the values of `nc`, as expected:
10691 >>> ncfdtrinc(2, 3, p, 15)
10692 array([ 0.5, 1.5, 2. ])
10694 """)
10696add_newdoc("nctdtr",
10697 """
10698 nctdtr(df, nc, t, out=None)
10700 Cumulative distribution function of the non-central `t` distribution.
10702 Parameters
10703 ----------
10704 df : array_like
10705 Degrees of freedom of the distribution. Should be in range (0, inf).
10706 nc : array_like
10707 Noncentrality parameter. Should be in range (-1e6, 1e6).
10708 t : array_like
10709 Quantiles, i.e., the upper limit of integration.
10710 out : ndarray, optional
10711 Optional output array for the function results
10713 Returns
10714 -------
10715 cdf : scalar or ndarray
10716 The calculated CDF. If all inputs are scalar, the return will be a
10717 float. Otherwise, it will be an array.
10719 See Also
10720 --------
10721 nctdtrit : Inverse CDF (iCDF) of the non-central t distribution.
10722 nctdtridf : Calculate degrees of freedom, given CDF and iCDF values.
10723 nctdtrinc : Calculate non-centrality parameter, given CDF iCDF values.
10725 Examples
10726 --------
10727 >>> import numpy as np
10728 >>> from scipy import special
10729 >>> from scipy import stats
10730 >>> import matplotlib.pyplot as plt
10732 Plot the CDF of the non-central t distribution, for nc=0. Compare with the
10733 t-distribution from scipy.stats:
10735 >>> x = np.linspace(-5, 5, num=500)
10736 >>> df = 3
10737 >>> nct_stats = stats.t.cdf(x, df)
10738 >>> nct_special = special.nctdtr(df, 0, x)
10740 >>> fig = plt.figure()
10741 >>> ax = fig.add_subplot(111)
10742 >>> ax.plot(x, nct_stats, 'b-', lw=3)
10743 >>> ax.plot(x, nct_special, 'r-')
10744 >>> plt.show()
10746 """)
10748add_newdoc("nctdtridf",
10749 """
10750 nctdtridf(p, nc, t, out=None)
10752 Calculate degrees of freedom for non-central t distribution.
10754 See `nctdtr` for more details.
10756 Parameters
10757 ----------
10758 p : array_like
10759 CDF values, in range (0, 1].
10760 nc : array_like
10761 Noncentrality parameter. Should be in range (-1e6, 1e6).
10762 t : array_like
10763 Quantiles, i.e., the upper limit of integration.
10764 out : ndarray, optional
10765 Optional output array for the function results
10767 Returns
10768 -------
10769 cdf : scalar or ndarray
10770 The calculated CDF. If all inputs are scalar, the return will be a
10771 float. Otherwise, it will be an array.
10773 See Also
10774 --------
10775 nctdtr : CDF of the non-central `t` distribution.
10776 nctdtrit : Inverse CDF (iCDF) of the non-central t distribution.
10777 nctdtrinc : Calculate non-centrality parameter, given CDF iCDF values.
10779 """)
10781add_newdoc("nctdtrinc",
10782 """
10783 nctdtrinc(df, p, t, out=None)
10785 Calculate non-centrality parameter for non-central t distribution.
10787 See `nctdtr` for more details.
10789 Parameters
10790 ----------
10791 df : array_like
10792 Degrees of freedom of the distribution. Should be in range (0, inf).
10793 p : array_like
10794 CDF values, in range (0, 1].
10795 t : array_like
10796 Quantiles, i.e., the upper limit of integration.
10797 out : ndarray, optional
10798 Optional output array for the function results
10800 Returns
10801 -------
10802 nc : scalar or ndarray
10803 Noncentrality parameter
10805 See Also
10806 --------
10807 nctdtr : CDF of the non-central `t` distribution.
10808 nctdtrit : Inverse CDF (iCDF) of the non-central t distribution.
10809 nctdtridf : Calculate degrees of freedom, given CDF and iCDF values.
10811 """)
10813add_newdoc("nctdtrit",
10814 """
10815 nctdtrit(df, nc, p, out=None)
10817 Inverse cumulative distribution function of the non-central t distribution.
10819 See `nctdtr` for more details.
10821 Parameters
10822 ----------
10823 df : array_like
10824 Degrees of freedom of the distribution. Should be in range (0, inf).
10825 nc : array_like
10826 Noncentrality parameter. Should be in range (-1e6, 1e6).
10827 p : array_like
10828 CDF values, in range (0, 1].
10829 out : ndarray, optional
10830 Optional output array for the function results
10832 Returns
10833 -------
10834 t : scalar or ndarray
10835 Quantiles
10837 See Also
10838 --------
10839 nctdtr : CDF of the non-central `t` distribution.
10840 nctdtridf : Calculate degrees of freedom, given CDF and iCDF values.
10841 nctdtrinc : Calculate non-centrality parameter, given CDF iCDF values.
10843 """)
10845add_newdoc("ndtr",
10846 r"""
10847 ndtr(x, out=None)
10849 Cumulative distribution of the standard normal distribution.
10851 Returns the area under the standard Gaussian probability
10852 density function, integrated from minus infinity to `x`
10854 .. math::
10856 \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x \exp(-t^2/2) dt
10858 Parameters
10859 ----------
10860 x : array_like, real or complex
10861 Argument
10862 out : ndarray, optional
10863 Optional output array for the function results
10865 Returns
10866 -------
10867 scalar or ndarray
10868 The value of the normal CDF evaluated at `x`
10870 See Also
10871 --------
10872 log_ndtr : Logarithm of ndtr
10873 ndtri : Inverse of ndtr, standard normal percentile function
10874 erf : Error function
10875 erfc : 1 - erf
10876 scipy.stats.norm : Normal distribution
10878 Examples
10879 --------
10880 Evaluate `ndtr` at one point.
10882 >>> import numpy as np
10883 >>> from scipy.special import ndtr
10884 >>> ndtr(0.5)
10885 0.6914624612740131
10887 Evaluate the function at several points by providing a NumPy array
10888 or list for `x`.
10890 >>> ndtr([0, 0.5, 2])
10891 array([0.5 , 0.69146246, 0.97724987])
10893 Plot the function.
10895 >>> import matplotlib.pyplot as plt
10896 >>> x = np.linspace(-5, 5, 100)
10897 >>> fig, ax = plt.subplots()
10898 >>> ax.plot(x, ndtr(x))
10899 >>> ax.set_title("Standard normal cumulative distribution function $\Phi$")
10900 >>> plt.show()
10901 """)
10904add_newdoc("nrdtrimn",
10905 """
10906 nrdtrimn(p, x, std, out=None)
10908 Calculate mean of normal distribution given other params.
10910 Parameters
10911 ----------
10912 p : array_like
10913 CDF values, in range (0, 1].
10914 x : array_like
10915 Quantiles, i.e. the upper limit of integration.
10916 std : array_like
10917 Standard deviation.
10918 out : ndarray, optional
10919 Optional output array for the function results
10921 Returns
10922 -------
10923 mn : scalar or ndarray
10924 The mean of the normal distribution.
10926 See Also
10927 --------
10928 nrdtrimn, ndtr
10930 """)
10932add_newdoc("nrdtrisd",
10933 """
10934 nrdtrisd(p, x, mn, out=None)
10936 Calculate standard deviation of normal distribution given other params.
10938 Parameters
10939 ----------
10940 p : array_like
10941 CDF values, in range (0, 1].
10942 x : array_like
10943 Quantiles, i.e. the upper limit of integration.
10944 mn : scalar or ndarray
10945 The mean of the normal distribution.
10946 out : ndarray, optional
10947 Optional output array for the function results
10949 Returns
10950 -------
10951 std : scalar or ndarray
10952 Standard deviation.
10954 See Also
10955 --------
10956 ndtr
10958 """)
10960add_newdoc("log_ndtr",
10961 """
10962 log_ndtr(x, out=None)
10964 Logarithm of Gaussian cumulative distribution function.
10966 Returns the log of the area under the standard Gaussian probability
10967 density function, integrated from minus infinity to `x`::
10969 log(1/sqrt(2*pi) * integral(exp(-t**2 / 2), t=-inf..x))
10971 Parameters
10972 ----------
10973 x : array_like, real or complex
10974 Argument
10975 out : ndarray, optional
10976 Optional output array for the function results
10978 Returns
10979 -------
10980 scalar or ndarray
10981 The value of the log of the normal CDF evaluated at `x`
10983 See Also
10984 --------
10985 erf
10986 erfc
10987 scipy.stats.norm
10988 ndtr
10990 Examples
10991 --------
10992 >>> import numpy as np
10993 >>> from scipy.special import log_ndtr, ndtr
10995 The benefit of ``log_ndtr(x)`` over the naive implementation
10996 ``np.log(ndtr(x))`` is most evident with moderate to large positive
10997 values of ``x``:
10999 >>> x = np.array([6, 7, 9, 12, 15, 25])
11000 >>> log_ndtr(x)
11001 array([-9.86587646e-010, -1.27981254e-012, -1.12858841e-019,
11002 -1.77648211e-033, -3.67096620e-051, -3.05669671e-138])
11004 The results of the naive calculation for the moderate ``x`` values
11005 have only 5 or 6 correct significant digits. For values of ``x``
11006 greater than approximately 8.3, the naive expression returns 0:
11008 >>> np.log(ndtr(x))
11009 array([-9.86587701e-10, -1.27986510e-12, 0.00000000e+00,
11010 0.00000000e+00, 0.00000000e+00, 0.00000000e+00])
11011 """)
11013add_newdoc("ndtri",
11014 """
11015 ndtri(y, out=None)
11017 Inverse of `ndtr` vs x
11019 Returns the argument x for which the area under the standard normal
11020 probability density function (integrated from minus infinity to `x`)
11021 is equal to y.
11023 Parameters
11024 ----------
11025 p : array_like
11026 Probability
11027 out : ndarray, optional
11028 Optional output array for the function results
11030 Returns
11031 -------
11032 x : scalar or ndarray
11033 Value of x such that ``ndtr(x) == p``.
11035 See Also
11036 --------
11037 ndtr : Standard normal cumulative probability distribution
11038 ndtri_exp : Inverse of log_ndtr
11040 Examples
11041 --------
11042 `ndtri` is the percentile function of the standard normal distribution.
11043 This means it returns the inverse of the cumulative density `ndtr`. First,
11044 let us compute a cumulative density value.
11046 >>> import numpy as np
11047 >>> from scipy.special import ndtri, ndtr
11048 >>> cdf_val = ndtr(2)
11049 >>> cdf_val
11050 0.9772498680518208
11052 Verify that `ndtri` yields the original value for `x` up to floating point
11053 errors.
11055 >>> ndtri(cdf_val)
11056 2.0000000000000004
11058 Plot the function. For that purpose, we provide a NumPy array as argument.
11060 >>> import matplotlib.pyplot as plt
11061 >>> x = np.linspace(0.01, 1, 200)
11062 >>> fig, ax = plt.subplots()
11063 >>> ax.plot(x, ndtri(x))
11064 >>> ax.set_title("Standard normal percentile function")
11065 >>> plt.show()
11066 """)
11068add_newdoc("obl_ang1",
11069 """
11070 obl_ang1(m, n, c, x, out=None)
11072 Oblate spheroidal angular function of the first kind and its derivative
11074 Computes the oblate spheroidal angular function of the first kind
11075 and its derivative (with respect to `x`) for mode parameters m>=0
11076 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11078 Parameters
11079 ----------
11080 m : array_like
11081 Mode parameter m (nonnegative)
11082 n : array_like
11083 Mode parameter n (>= m)
11084 c : array_like
11085 Spheroidal parameter
11086 x : array_like
11087 Parameter x (``|x| < 1.0``)
11088 out : ndarray, optional
11089 Optional output array for the function results
11091 Returns
11092 -------
11093 s : scalar or ndarray
11094 Value of the function
11095 sp : scalar or ndarray
11096 Value of the derivative vs x
11098 See Also
11099 --------
11100 obl_ang1_cv
11102 """)
11104add_newdoc("obl_ang1_cv",
11105 """
11106 obl_ang1_cv(m, n, c, cv, x, out=None)
11108 Oblate spheroidal angular function obl_ang1 for precomputed characteristic value
11110 Computes the oblate spheroidal angular function of the first kind
11111 and its derivative (with respect to `x`) for mode parameters m>=0
11112 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11113 pre-computed characteristic value.
11115 Parameters
11116 ----------
11117 m : array_like
11118 Mode parameter m (nonnegative)
11119 n : array_like
11120 Mode parameter n (>= m)
11121 c : array_like
11122 Spheroidal parameter
11123 cv : array_like
11124 Characteristic value
11125 x : array_like
11126 Parameter x (``|x| < 1.0``)
11127 out : ndarray, optional
11128 Optional output array for the function results
11130 Returns
11131 -------
11132 s : scalar or ndarray
11133 Value of the function
11134 sp : scalar or ndarray
11135 Value of the derivative vs x
11137 See Also
11138 --------
11139 obl_ang1
11141 """)
11143add_newdoc("obl_cv",
11144 """
11145 obl_cv(m, n, c, out=None)
11147 Characteristic value of oblate spheroidal function
11149 Computes the characteristic value of oblate spheroidal wave
11150 functions of order `m`, `n` (n>=m) and spheroidal parameter `c`.
11152 Parameters
11153 ----------
11154 m : array_like
11155 Mode parameter m (nonnegative)
11156 n : array_like
11157 Mode parameter n (>= m)
11158 c : array_like
11159 Spheroidal parameter
11160 out : ndarray, optional
11161 Optional output array for the function results
11163 Returns
11164 -------
11165 cv : scalar or ndarray
11166 Characteristic value
11168 """)
11170add_newdoc("obl_rad1",
11171 """
11172 obl_rad1(m, n, c, x, out=None)
11174 Oblate spheroidal radial function of the first kind and its derivative
11176 Computes the oblate spheroidal radial function of the first kind
11177 and its derivative (with respect to `x`) for mode parameters m>=0
11178 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11180 Parameters
11181 ----------
11182 m : array_like
11183 Mode parameter m (nonnegative)
11184 n : array_like
11185 Mode parameter n (>= m)
11186 c : array_like
11187 Spheroidal parameter
11188 x : array_like
11189 Parameter x (``|x| < 1.0``)
11190 out : ndarray, optional
11191 Optional output array for the function results
11193 Returns
11194 -------
11195 s : scalar or ndarray
11196 Value of the function
11197 sp : scalar or ndarray
11198 Value of the derivative vs x
11200 See Also
11201 --------
11202 obl_rad1_cv
11204 """)
11206add_newdoc("obl_rad1_cv",
11207 """
11208 obl_rad1_cv(m, n, c, cv, x, out=None)
11210 Oblate spheroidal radial function obl_rad1 for precomputed characteristic value
11212 Computes the oblate spheroidal radial function of the first kind
11213 and its derivative (with respect to `x`) for mode parameters m>=0
11214 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11215 pre-computed characteristic value.
11217 Parameters
11218 ----------
11219 m : array_like
11220 Mode parameter m (nonnegative)
11221 n : array_like
11222 Mode parameter n (>= m)
11223 c : array_like
11224 Spheroidal parameter
11225 cv : array_like
11226 Characteristic value
11227 x : array_like
11228 Parameter x (``|x| < 1.0``)
11229 out : ndarray, optional
11230 Optional output array for the function results
11232 Returns
11233 -------
11234 s : scalar or ndarray
11235 Value of the function
11236 sp : scalar or ndarray
11237 Value of the derivative vs x
11239 See Also
11240 --------
11241 obl_rad1
11243 """)
11245add_newdoc("obl_rad2",
11246 """
11247 obl_rad2(m, n, c, x, out=None)
11249 Oblate spheroidal radial function of the second kind and its derivative.
11251 Computes the oblate spheroidal radial function of the second kind
11252 and its derivative (with respect to `x`) for mode parameters m>=0
11253 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11255 Parameters
11256 ----------
11257 m : array_like
11258 Mode parameter m (nonnegative)
11259 n : array_like
11260 Mode parameter n (>= m)
11261 c : array_like
11262 Spheroidal parameter
11263 x : array_like
11264 Parameter x (``|x| < 1.0``)
11265 out : ndarray, optional
11266 Optional output array for the function results
11268 Returns
11269 -------
11270 s : scalar or ndarray
11271 Value of the function
11272 sp : scalar or ndarray
11273 Value of the derivative vs x
11275 See Also
11276 --------
11277 obl_rad2_cv
11279 """)
11281add_newdoc("obl_rad2_cv",
11282 """
11283 obl_rad2_cv(m, n, c, cv, x, out=None)
11285 Oblate spheroidal radial function obl_rad2 for precomputed characteristic value
11287 Computes the oblate spheroidal radial function of the second kind
11288 and its derivative (with respect to `x`) for mode parameters m>=0
11289 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11290 pre-computed characteristic value.
11292 Parameters
11293 ----------
11294 m : array_like
11295 Mode parameter m (nonnegative)
11296 n : array_like
11297 Mode parameter n (>= m)
11298 c : array_like
11299 Spheroidal parameter
11300 cv : array_like
11301 Characteristic value
11302 x : array_like
11303 Parameter x (``|x| < 1.0``)
11304 out : ndarray, optional
11305 Optional output array for the function results
11307 Returns
11308 -------
11309 s : scalar or ndarray
11310 Value of the function
11311 sp : scalar or ndarray
11312 Value of the derivative vs x
11314 See Also
11315 --------
11316 obl_rad2
11317 """)
11319add_newdoc("pbdv",
11320 """
11321 pbdv(v, x, out=None)
11323 Parabolic cylinder function D
11325 Returns (d, dp) the parabolic cylinder function Dv(x) in d and the
11326 derivative, Dv'(x) in dp.
11328 Parameters
11329 ----------
11330 v : array_like
11331 Real parameter
11332 x : array_like
11333 Real argument
11334 out : ndarray, optional
11335 Optional output array for the function results
11337 Returns
11338 -------
11339 d : scalar or ndarray
11340 Value of the function
11341 dp : scalar or ndarray
11342 Value of the derivative vs x
11343 """)
11345add_newdoc("pbvv",
11346 """
11347 pbvv(v, x, out=None)
11349 Parabolic cylinder function V
11351 Returns the parabolic cylinder function Vv(x) in v and the
11352 derivative, Vv'(x) in vp.
11354 Parameters
11355 ----------
11356 v : array_like
11357 Real parameter
11358 x : array_like
11359 Real argument
11360 out : ndarray, optional
11361 Optional output array for the function results
11363 Returns
11364 -------
11365 v : scalar or ndarray
11366 Value of the function
11367 vp : scalar or ndarray
11368 Value of the derivative vs x
11369 """)
11371add_newdoc("pbwa",
11372 r"""
11373 pbwa(a, x, out=None)
11375 Parabolic cylinder function W.
11377 The function is a particular solution to the differential equation
11379 .. math::
11381 y'' + \left(\frac{1}{4}x^2 - a\right)y = 0,
11383 for a full definition see section 12.14 in [1]_.
11385 Parameters
11386 ----------
11387 a : array_like
11388 Real parameter
11389 x : array_like
11390 Real argument
11391 out : ndarray, optional
11392 Optional output array for the function results
11394 Returns
11395 -------
11396 w : scalar or ndarray
11397 Value of the function
11398 wp : scalar or ndarray
11399 Value of the derivative in x
11401 Notes
11402 -----
11403 The function is a wrapper for a Fortran routine by Zhang and Jin
11404 [2]_. The implementation is accurate only for ``|a|, |x| < 5`` and
11405 returns NaN outside that range.
11407 References
11408 ----------
11409 .. [1] Digital Library of Mathematical Functions, 14.30.
11410 https://dlmf.nist.gov/14.30
11411 .. [2] Zhang, Shanjie and Jin, Jianming. "Computation of Special
11412 Functions", John Wiley and Sons, 1996.
11413 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
11414 """)
11416add_newdoc("pdtr",
11417 r"""
11418 pdtr(k, m, out=None)
11420 Poisson cumulative distribution function.
11422 Defined as the probability that a Poisson-distributed random
11423 variable with event rate :math:`m` is less than or equal to
11424 :math:`k`. More concretely, this works out to be [1]_
11426 .. math::
11428 \exp(-m) \sum_{j = 0}^{\lfloor{k}\rfloor} \frac{m^j}{j!}.
11430 Parameters
11431 ----------
11432 k : array_like
11433 Number of occurrences (nonnegative, real)
11434 m : array_like
11435 Shape parameter (nonnegative, real)
11436 out : ndarray, optional
11437 Optional output array for the function results
11439 Returns
11440 -------
11441 scalar or ndarray
11442 Values of the Poisson cumulative distribution function
11444 See Also
11445 --------
11446 pdtrc : Poisson survival function
11447 pdtrik : inverse of `pdtr` with respect to `k`
11448 pdtri : inverse of `pdtr` with respect to `m`
11450 References
11451 ----------
11452 .. [1] https://en.wikipedia.org/wiki/Poisson_distribution
11454 Examples
11455 --------
11456 >>> import numpy as np
11457 >>> import scipy.special as sc
11459 It is a cumulative distribution function, so it converges to 1
11460 monotonically as `k` goes to infinity.
11462 >>> sc.pdtr([1, 10, 100, np.inf], 1)
11463 array([0.73575888, 0.99999999, 1. , 1. ])
11465 It is discontinuous at integers and constant between integers.
11467 >>> sc.pdtr([1, 1.5, 1.9, 2], 1)
11468 array([0.73575888, 0.73575888, 0.73575888, 0.9196986 ])
11470 """)
11472add_newdoc("pdtrc",
11473 """
11474 pdtrc(k, m, out=None)
11476 Poisson survival function
11478 Returns the sum of the terms from k+1 to infinity of the Poisson
11479 distribution: sum(exp(-m) * m**j / j!, j=k+1..inf) = gammainc(
11480 k+1, m). Arguments must both be non-negative doubles.
11482 Parameters
11483 ----------
11484 k : array_like
11485 Number of occurrences (nonnegative, real)
11486 m : array_like
11487 Shape parameter (nonnegative, real)
11488 out : ndarray, optional
11489 Optional output array for the function results
11491 Returns
11492 -------
11493 scalar or ndarray
11494 Values of the Poisson survival function
11496 See Also
11497 --------
11498 pdtr : Poisson cumulative distribution function
11499 pdtrik : inverse of `pdtr` with respect to `k`
11500 pdtri : inverse of `pdtr` with respect to `m`
11502 """)
11504add_newdoc("pdtri",
11505 """
11506 pdtri(k, y, out=None)
11508 Inverse to `pdtr` vs m
11510 Returns the Poisson variable `m` such that the sum from 0 to `k` of
11511 the Poisson density is equal to the given probability `y`:
11512 calculated by ``gammaincinv(k + 1, y)``. `k` must be a nonnegative
11513 integer and `y` between 0 and 1.
11515 Parameters
11516 ----------
11517 k : array_like
11518 Number of occurrences (nonnegative, real)
11519 y : array_like
11520 Probability
11521 out : ndarray, optional
11522 Optional output array for the function results
11524 Returns
11525 -------
11526 scalar or ndarray
11527 Values of the shape paramter `m` such that ``pdtr(k, m) = p``
11529 See Also
11530 --------
11531 pdtr : Poisson cumulative distribution function
11532 pdtrc : Poisson survival function
11533 pdtrik : inverse of `pdtr` with respect to `k`
11535 """)
11537add_newdoc("pdtrik",
11538 """
11539 pdtrik(p, m, out=None)
11541 Inverse to `pdtr` vs `m`.
11543 Parameters
11544 ----------
11545 m : array_like
11546 Shape parameter (nonnegative, real)
11547 p : array_like
11548 Probability
11549 out : ndarray, optional
11550 Optional output array for the function results
11552 Returns
11553 -------
11554 scalar or ndarray
11555 The number of occurrences `k` such that ``pdtr(k, m) = p``
11557 See Also
11558 --------
11559 pdtr : Poisson cumulative distribution function
11560 pdtrc : Poisson survival function
11561 pdtri : inverse of `pdtr` with respect to `m`
11563 """)
11565add_newdoc("poch",
11566 r"""
11567 poch(z, m, out=None)
11569 Pochhammer symbol.
11571 The Pochhammer symbol (rising factorial) is defined as
11573 .. math::
11575 (z)_m = \frac{\Gamma(z + m)}{\Gamma(z)}
11577 For positive integer `m` it reads
11579 .. math::
11581 (z)_m = z (z + 1) ... (z + m - 1)
11583 See [dlmf]_ for more details.
11585 Parameters
11586 ----------
11587 z, m : array_like
11588 Real-valued arguments.
11589 out : ndarray, optional
11590 Optional output array for the function results
11592 Returns
11593 -------
11594 scalar or ndarray
11595 The value of the function.
11597 References
11598 ----------
11599 .. [dlmf] Nist, Digital Library of Mathematical Functions
11600 https://dlmf.nist.gov/5.2#iii
11602 Examples
11603 --------
11604 >>> import scipy.special as sc
11606 It is 1 when m is 0.
11608 >>> sc.poch([1, 2, 3, 4], 0)
11609 array([1., 1., 1., 1.])
11611 For z equal to 1 it reduces to the factorial function.
11613 >>> sc.poch(1, 5)
11614 120.0
11615 >>> 1 * 2 * 3 * 4 * 5
11616 120
11618 It can be expressed in terms of the gamma function.
11620 >>> z, m = 3.7, 2.1
11621 >>> sc.poch(z, m)
11622 20.529581933776953
11623 >>> sc.gamma(z + m) / sc.gamma(z)
11624 20.52958193377696
11626 """)
11628add_newdoc("powm1", """
11629 powm1(x, y, out=None)
11631 Computes ``x**y - 1``.
11633 This function is useful when `y` is near 0, or when `x` is near 1.
11635 The function is implemented for real types only (unlike ``numpy.power``,
11636 which accepts complex inputs).
11638 Parameters
11639 ----------
11640 x : array_like
11641 The base. Must be a real type (i.e. integer or float, not complex).
11642 y : array_like
11643 The exponent. Must be a real type (i.e. integer or float, not complex).
11645 Returns
11646 -------
11647 array_like
11648 Result of the calculation
11650 Notes
11651 -----
11652 .. versionadded:: 1.10.0
11654 The underlying code is implemented for single precision and double
11655 precision floats only. Unlike `numpy.power`, integer inputs to
11656 `powm1` are converted to floating point, and complex inputs are
11657 not accepted.
11659 Note the following edge cases:
11661 * ``powm1(x, 0)`` returns 0 for any ``x``, including 0, ``inf``
11662 and ``nan``.
11663 * ``powm1(1, y)`` returns 0 for any ``y``, including ``nan``
11664 and ``inf``.
11666 Examples
11667 --------
11668 >>> import numpy as np
11669 >>> from scipy.special import powm1
11671 >>> x = np.array([1.2, 10.0, 0.9999999975])
11672 >>> y = np.array([1e-9, 1e-11, 0.1875])
11673 >>> powm1(x, y)
11674 array([ 1.82321557e-10, 2.30258509e-11, -4.68749998e-10])
11676 It can be verified that the relative errors in those results
11677 are less than 2.5e-16.
11679 Compare that to the result of ``x**y - 1``, where the
11680 relative errors are all larger than 8e-8:
11682 >>> x**y - 1
11683 array([ 1.82321491e-10, 2.30258035e-11, -4.68750039e-10])
11685 """)
11688add_newdoc("pro_ang1",
11689 """
11690 pro_ang1(m, n, c, x, out=None)
11692 Prolate spheroidal angular function of the first kind and its derivative
11694 Computes the prolate spheroidal angular function of the first kind
11695 and its derivative (with respect to `x`) for mode parameters m>=0
11696 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11698 Parameters
11699 ----------
11700 m : array_like
11701 Nonnegative mode parameter m
11702 n : array_like
11703 Mode parameter n (>= m)
11704 c : array_like
11705 Spheroidal parameter
11706 x : array_like
11707 Real parameter (``|x| < 1.0``)
11708 out : ndarray, optional
11709 Optional output array for the function results
11711 Returns
11712 -------
11713 s : scalar or ndarray
11714 Value of the function
11715 sp : scalar or ndarray
11716 Value of the derivative vs x
11717 """)
11719add_newdoc("pro_ang1_cv",
11720 """
11721 pro_ang1_cv(m, n, c, cv, x, out=None)
11723 Prolate spheroidal angular function pro_ang1 for precomputed characteristic value
11725 Computes the prolate spheroidal angular function of the first kind
11726 and its derivative (with respect to `x`) for mode parameters m>=0
11727 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11728 pre-computed characteristic value.
11730 Parameters
11731 ----------
11732 m : array_like
11733 Nonnegative mode parameter m
11734 n : array_like
11735 Mode parameter n (>= m)
11736 c : array_like
11737 Spheroidal parameter
11738 cv : array_like
11739 Characteristic value
11740 x : array_like
11741 Real parameter (``|x| < 1.0``)
11742 out : ndarray, optional
11743 Optional output array for the function results
11745 Returns
11746 -------
11747 s : scalar or ndarray
11748 Value of the function
11749 sp : scalar or ndarray
11750 Value of the derivative vs x
11751 """)
11753add_newdoc("pro_cv",
11754 """
11755 pro_cv(m, n, c, out=None)
11757 Characteristic value of prolate spheroidal function
11759 Computes the characteristic value of prolate spheroidal wave
11760 functions of order `m`, `n` (n>=m) and spheroidal parameter `c`.
11762 Parameters
11763 ----------
11764 m : array_like
11765 Nonnegative mode parameter m
11766 n : array_like
11767 Mode parameter n (>= m)
11768 c : array_like
11769 Spheroidal parameter
11770 out : ndarray, optional
11771 Optional output array for the function results
11773 Returns
11774 -------
11775 cv : scalar or ndarray
11776 Characteristic value
11777 """)
11779add_newdoc("pro_rad1",
11780 """
11781 pro_rad1(m, n, c, x, out=None)
11783 Prolate spheroidal radial function of the first kind and its derivative
11785 Computes the prolate spheroidal radial function of the first kind
11786 and its derivative (with respect to `x`) for mode parameters m>=0
11787 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11789 Parameters
11790 ----------
11791 m : array_like
11792 Nonnegative mode parameter m
11793 n : array_like
11794 Mode parameter n (>= m)
11795 c : array_like
11796 Spheroidal parameter
11797 x : array_like
11798 Real parameter (``|x| < 1.0``)
11799 out : ndarray, optional
11800 Optional output array for the function results
11802 Returns
11803 -------
11804 s : scalar or ndarray
11805 Value of the function
11806 sp : scalar or ndarray
11807 Value of the derivative vs x
11808 """)
11810add_newdoc("pro_rad1_cv",
11811 """
11812 pro_rad1_cv(m, n, c, cv, x, out=None)
11814 Prolate spheroidal radial function pro_rad1 for precomputed characteristic value
11816 Computes the prolate spheroidal radial function of the first kind
11817 and its derivative (with respect to `x`) for mode parameters m>=0
11818 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11819 pre-computed characteristic value.
11821 Parameters
11822 ----------
11823 m : array_like
11824 Nonnegative mode parameter m
11825 n : array_like
11826 Mode parameter n (>= m)
11827 c : array_like
11828 Spheroidal parameter
11829 cv : array_like
11830 Characteristic value
11831 x : array_like
11832 Real parameter (``|x| < 1.0``)
11833 out : ndarray, optional
11834 Optional output array for the function results
11836 Returns
11837 -------
11838 s : scalar or ndarray
11839 Value of the function
11840 sp : scalar or ndarray
11841 Value of the derivative vs x
11842 """)
11844add_newdoc("pro_rad2",
11845 """
11846 pro_rad2(m, n, c, x, out=None)
11848 Prolate spheroidal radial function of the second kind and its derivative
11850 Computes the prolate spheroidal radial function of the second kind
11851 and its derivative (with respect to `x`) for mode parameters m>=0
11852 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11854 Parameters
11855 ----------
11856 m : array_like
11857 Nonnegative mode parameter m
11858 n : array_like
11859 Mode parameter n (>= m)
11860 c : array_like
11861 Spheroidal parameter
11862 cv : array_like
11863 Characteristic value
11864 x : array_like
11865 Real parameter (``|x| < 1.0``)
11866 out : ndarray, optional
11867 Optional output array for the function results
11869 Returns
11870 -------
11871 s : scalar or ndarray
11872 Value of the function
11873 sp : scalar or ndarray
11874 Value of the derivative vs x
11875 """)
11877add_newdoc("pro_rad2_cv",
11878 """
11879 pro_rad2_cv(m, n, c, cv, x, out=None)
11881 Prolate spheroidal radial function pro_rad2 for precomputed characteristic value
11883 Computes the prolate spheroidal radial function of the second kind
11884 and its derivative (with respect to `x`) for mode parameters m>=0
11885 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11886 pre-computed characteristic value.
11888 Parameters
11889 ----------
11890 m : array_like
11891 Nonnegative mode parameter m
11892 n : array_like
11893 Mode parameter n (>= m)
11894 c : array_like
11895 Spheroidal parameter
11896 cv : array_like
11897 Characteristic value
11898 x : array_like
11899 Real parameter (``|x| < 1.0``)
11900 out : ndarray, optional
11901 Optional output array for the function results
11903 Returns
11904 -------
11905 s : scalar or ndarray
11906 Value of the function
11907 sp : scalar or ndarray
11908 Value of the derivative vs x
11909 """)
11911add_newdoc("pseudo_huber",
11912 r"""
11913 pseudo_huber(delta, r, out=None)
11915 Pseudo-Huber loss function.
11917 .. math:: \mathrm{pseudo\_huber}(\delta, r) = \delta^2 \left( \sqrt{ 1 + \left( \frac{r}{\delta} \right)^2 } - 1 \right)
11919 Parameters
11920 ----------
11921 delta : array_like
11922 Input array, indicating the soft quadratic vs. linear loss changepoint.
11923 r : array_like
11924 Input array, possibly representing residuals.
11925 out : ndarray, optional
11926 Optional output array for the function results
11928 Returns
11929 -------
11930 res : scalar or ndarray
11931 The computed Pseudo-Huber loss function values.
11933 See also
11934 --------
11935 huber: Similar function which this function approximates
11937 Notes
11938 -----
11939 Like `huber`, `pseudo_huber` often serves as a robust loss function
11940 in statistics or machine learning to reduce the influence of outliers.
11941 Unlike `huber`, `pseudo_huber` is smooth.
11943 Typically, `r` represents residuals, the difference
11944 between a model prediction and data. Then, for :math:`|r|\leq\delta`,
11945 `pseudo_huber` resembles the squared error and for :math:`|r|>\delta` the
11946 absolute error. This way, the Pseudo-Huber loss often achieves
11947 a fast convergence in model fitting for small residuals like the squared
11948 error loss function and still reduces the influence of outliers
11949 (:math:`|r|>\delta`) like the absolute error loss. As :math:`\delta` is
11950 the cutoff between squared and absolute error regimes, it has
11951 to be tuned carefully for each problem. `pseudo_huber` is also
11952 convex, making it suitable for gradient based optimization. [1]_ [2]_
11954 .. versionadded:: 0.15.0
11956 References
11957 ----------
11958 .. [1] Hartley, Zisserman, "Multiple View Geometry in Computer Vision".
11959 2003. Cambridge University Press. p. 619
11960 .. [2] Charbonnier et al. "Deterministic edge-preserving regularization
11961 in computed imaging". 1997. IEEE Trans. Image Processing.
11962 6 (2): 298 - 311.
11964 Examples
11965 --------
11966 Import all necessary modules.
11968 >>> import numpy as np
11969 >>> from scipy.special import pseudo_huber, huber
11970 >>> import matplotlib.pyplot as plt
11972 Calculate the function for ``delta=1`` at ``r=2``.
11974 >>> pseudo_huber(1., 2.)
11975 1.2360679774997898
11977 Calculate the function at ``r=2`` for different `delta` by providing
11978 a list or NumPy array for `delta`.
11980 >>> pseudo_huber([1., 2., 4.], 3.)
11981 array([2.16227766, 3.21110255, 4. ])
11983 Calculate the function for ``delta=1`` at several points by providing
11984 a list or NumPy array for `r`.
11986 >>> pseudo_huber(2., np.array([1., 1.5, 3., 4.]))
11987 array([0.47213595, 1. , 3.21110255, 4.94427191])
11989 The function can be calculated for different `delta` and `r` by
11990 providing arrays for both with compatible shapes for broadcasting.
11992 >>> r = np.array([1., 2.5, 8., 10.])
11993 >>> deltas = np.array([[1.], [5.], [9.]])
11994 >>> print(r.shape, deltas.shape)
11995 (4,) (3, 1)
11997 >>> pseudo_huber(deltas, r)
11998 array([[ 0.41421356, 1.6925824 , 7.06225775, 9.04987562],
11999 [ 0.49509757, 2.95084972, 22.16990566, 30.90169944],
12000 [ 0.49846624, 3.06693762, 27.37435121, 40.08261642]])
12002 Plot the function for different `delta`.
12004 >>> x = np.linspace(-4, 4, 500)
12005 >>> deltas = [1, 2, 3]
12006 >>> linestyles = ["dashed", "dotted", "dashdot"]
12007 >>> fig, ax = plt.subplots()
12008 >>> combined_plot_parameters = list(zip(deltas, linestyles))
12009 >>> for delta, style in combined_plot_parameters:
12010 ... ax.plot(x, pseudo_huber(delta, x), label=f"$\delta={delta}$",
12011 ... ls=style)
12012 >>> ax.legend(loc="upper center")
12013 >>> ax.set_xlabel("$x$")
12014 >>> ax.set_title("Pseudo-Huber loss function $h_{\delta}(x)$")
12015 >>> ax.set_xlim(-4, 4)
12016 >>> ax.set_ylim(0, 8)
12017 >>> plt.show()
12019 Finally, illustrate the difference between `huber` and `pseudo_huber` by
12020 plotting them and their gradients with respect to `r`. The plot shows
12021 that `pseudo_huber` is continuously differentiable while `huber` is not
12022 at the points :math:`\pm\delta`.
12024 >>> def huber_grad(delta, x):
12025 ... grad = np.copy(x)
12026 ... linear_area = np.argwhere(np.abs(x) > delta)
12027 ... grad[linear_area]=delta*np.sign(x[linear_area])
12028 ... return grad
12029 >>> def pseudo_huber_grad(delta, x):
12030 ... return x* (1+(x/delta)**2)**(-0.5)
12031 >>> x=np.linspace(-3, 3, 500)
12032 >>> delta = 1.
12033 >>> fig, ax = plt.subplots(figsize=(7, 7))
12034 >>> ax.plot(x, huber(delta, x), label="Huber", ls="dashed")
12035 >>> ax.plot(x, huber_grad(delta, x), label="Huber Gradient", ls="dashdot")
12036 >>> ax.plot(x, pseudo_huber(delta, x), label="Pseudo-Huber", ls="dotted")
12037 >>> ax.plot(x, pseudo_huber_grad(delta, x), label="Pseudo-Huber Gradient",
12038 ... ls="solid")
12039 >>> ax.legend(loc="upper center")
12040 >>> plt.show()
12041 """)
12043add_newdoc("psi",
12044 """
12045 psi(z, out=None)
12047 The digamma function.
12049 The logarithmic derivative of the gamma function evaluated at ``z``.
12051 Parameters
12052 ----------
12053 z : array_like
12054 Real or complex argument.
12055 out : ndarray, optional
12056 Array for the computed values of ``psi``.
12058 Returns
12059 -------
12060 digamma : scalar or ndarray
12061 Computed values of ``psi``.
12063 Notes
12064 -----
12065 For large values not close to the negative real axis, ``psi`` is
12066 computed using the asymptotic series (5.11.2) from [1]_. For small
12067 arguments not close to the negative real axis, the recurrence
12068 relation (5.5.2) from [1]_ is used until the argument is large
12069 enough to use the asymptotic series. For values close to the
12070 negative real axis, the reflection formula (5.5.4) from [1]_ is
12071 used first. Note that ``psi`` has a family of zeros on the
12072 negative real axis which occur between the poles at nonpositive
12073 integers. Around the zeros the reflection formula suffers from
12074 cancellation and the implementation loses precision. The sole
12075 positive zero and the first negative zero, however, are handled
12076 separately by precomputing series expansions using [2]_, so the
12077 function should maintain full accuracy around the origin.
12079 References
12080 ----------
12081 .. [1] NIST Digital Library of Mathematical Functions
12082 https://dlmf.nist.gov/5
12083 .. [2] Fredrik Johansson and others.
12084 "mpmath: a Python library for arbitrary-precision floating-point arithmetic"
12085 (Version 0.19) http://mpmath.org/
12087 Examples
12088 --------
12089 >>> from scipy.special import psi
12090 >>> z = 3 + 4j
12091 >>> psi(z)
12092 (1.55035981733341+1.0105022091860445j)
12094 Verify psi(z) = psi(z + 1) - 1/z:
12096 >>> psi(z + 1) - 1/z
12097 (1.55035981733341+1.0105022091860445j)
12098 """)
12100add_newdoc("radian",
12101 """
12102 radian(d, m, s, out=None)
12104 Convert from degrees to radians.
12106 Returns the angle given in (d)egrees, (m)inutes, and (s)econds in
12107 radians.
12109 Parameters
12110 ----------
12111 d : array_like
12112 Degrees, can be real-valued.
12113 m : array_like
12114 Minutes, can be real-valued.
12115 s : array_like
12116 Seconds, can be real-valued.
12117 out : ndarray, optional
12118 Optional output array for the function results.
12120 Returns
12121 -------
12122 scalar or ndarray
12123 Values of the inputs in radians.
12125 Examples
12126 --------
12127 >>> import scipy.special as sc
12129 There are many ways to specify an angle.
12131 >>> sc.radian(90, 0, 0)
12132 1.5707963267948966
12133 >>> sc.radian(0, 60 * 90, 0)
12134 1.5707963267948966
12135 >>> sc.radian(0, 0, 60**2 * 90)
12136 1.5707963267948966
12138 The inputs can be real-valued.
12140 >>> sc.radian(1.5, 0, 0)
12141 0.02617993877991494
12142 >>> sc.radian(1, 30, 0)
12143 0.02617993877991494
12145 """)
12147add_newdoc("rel_entr",
12148 r"""
12149 rel_entr(x, y, out=None)
12151 Elementwise function for computing relative entropy.
12153 .. math::
12155 \mathrm{rel\_entr}(x, y) =
12156 \begin{cases}
12157 x \log(x / y) & x > 0, y > 0 \\
12158 0 & x = 0, y \ge 0 \\
12159 \infty & \text{otherwise}
12160 \end{cases}
12162 Parameters
12163 ----------
12164 x, y : array_like
12165 Input arrays
12166 out : ndarray, optional
12167 Optional output array for the function results
12169 Returns
12170 -------
12171 scalar or ndarray
12172 Relative entropy of the inputs
12174 See Also
12175 --------
12176 entr, kl_div, scipy.stats.entropy
12178 Notes
12179 -----
12180 .. versionadded:: 0.15.0
12182 This function is jointly convex in x and y.
12184 The origin of this function is in convex programming; see
12185 [1]_. Given two discrete probability distributions :math:`p_1,
12186 \ldots, p_n` and :math:`q_1, \ldots, q_n`, the definition of relative
12187 entropy in the context of *information theory* is
12189 .. math::
12191 \sum_{i = 1}^n \mathrm{rel\_entr}(p_i, q_i).
12193 To compute the latter quantity, use `scipy.stats.entropy`.
12195 See [2]_ for details.
12197 References
12198 ----------
12199 .. [1] Boyd, Stephen and Lieven Vandenberghe. *Convex optimization*.
12200 Cambridge University Press, 2004.
12201 :doi:`https://doi.org/10.1017/CBO9780511804441`
12202 .. [2] Kullback-Leibler divergence,
12203 https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence
12205 """)
12207add_newdoc("rgamma",
12208 r"""
12209 rgamma(z, out=None)
12211 Reciprocal of the gamma function.
12213 Defined as :math:`1 / \Gamma(z)`, where :math:`\Gamma` is the
12214 gamma function. For more on the gamma function see `gamma`.
12216 Parameters
12217 ----------
12218 z : array_like
12219 Real or complex valued input
12220 out : ndarray, optional
12221 Optional output array for the function results
12223 Returns
12224 -------
12225 scalar or ndarray
12226 Function results
12228 Notes
12229 -----
12230 The gamma function has no zeros and has simple poles at
12231 nonpositive integers, so `rgamma` is an entire function with zeros
12232 at the nonpositive integers. See the discussion in [dlmf]_ for
12233 more details.
12235 See Also
12236 --------
12237 gamma, gammaln, loggamma
12239 References
12240 ----------
12241 .. [dlmf] Nist, Digital Library of Mathematical functions,
12242 https://dlmf.nist.gov/5.2#i
12244 Examples
12245 --------
12246 >>> import scipy.special as sc
12248 It is the reciprocal of the gamma function.
12250 >>> sc.rgamma([1, 2, 3, 4])
12251 array([1. , 1. , 0.5 , 0.16666667])
12252 >>> 1 / sc.gamma([1, 2, 3, 4])
12253 array([1. , 1. , 0.5 , 0.16666667])
12255 It is zero at nonpositive integers.
12257 >>> sc.rgamma([0, -1, -2, -3])
12258 array([0., 0., 0., 0.])
12260 It rapidly underflows to zero along the positive real axis.
12262 >>> sc.rgamma([10, 100, 179])
12263 array([2.75573192e-006, 1.07151029e-156, 0.00000000e+000])
12265 """)
12267add_newdoc("round",
12268 """
12269 round(x, out=None)
12271 Round to the nearest integer.
12273 Returns the nearest integer to `x`. If `x` ends in 0.5 exactly,
12274 the nearest even integer is chosen.
12276 Parameters
12277 ----------
12278 x : array_like
12279 Real valued input.
12280 out : ndarray, optional
12281 Optional output array for the function results.
12283 Returns
12284 -------
12285 scalar or ndarray
12286 The nearest integers to the elements of `x`. The result is of
12287 floating type, not integer type.
12289 Examples
12290 --------
12291 >>> import scipy.special as sc
12293 It rounds to even.
12295 >>> sc.round([0.5, 1.5])
12296 array([0., 2.])
12298 """)
12300add_newdoc("shichi",
12301 r"""
12302 shichi(x, out=None)
12304 Hyperbolic sine and cosine integrals.
12306 The hyperbolic sine integral is
12308 .. math::
12310 \int_0^x \frac{\sinh{t}}{t}dt
12312 and the hyperbolic cosine integral is
12314 .. math::
12316 \gamma + \log(x) + \int_0^x \frac{\cosh{t} - 1}{t} dt
12318 where :math:`\gamma` is Euler's constant and :math:`\log` is the
12319 principal branch of the logarithm [1]_.
12321 Parameters
12322 ----------
12323 x : array_like
12324 Real or complex points at which to compute the hyperbolic sine
12325 and cosine integrals.
12326 out : tuple of ndarray, optional
12327 Optional output arrays for the function results
12329 Returns
12330 -------
12331 si : scalar or ndarray
12332 Hyperbolic sine integral at ``x``
12333 ci : scalar or ndarray
12334 Hyperbolic cosine integral at ``x``
12336 See Also
12337 --------
12338 sici : Sine and cosine integrals.
12339 exp1 : Exponential integral E1.
12340 expi : Exponential integral Ei.
12342 Notes
12343 -----
12344 For real arguments with ``x < 0``, ``chi`` is the real part of the
12345 hyperbolic cosine integral. For such points ``chi(x)`` and ``chi(x
12346 + 0j)`` differ by a factor of ``1j*pi``.
12348 For real arguments the function is computed by calling Cephes'
12349 [2]_ *shichi* routine. For complex arguments the algorithm is based
12350 on Mpmath's [3]_ *shi* and *chi* routines.
12352 References
12353 ----------
12354 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
12355 Handbook of Mathematical Functions with Formulas,
12356 Graphs, and Mathematical Tables. New York: Dover, 1972.
12357 (See Section 5.2.)
12358 .. [2] Cephes Mathematical Functions Library,
12359 http://www.netlib.org/cephes/
12360 .. [3] Fredrik Johansson and others.
12361 "mpmath: a Python library for arbitrary-precision floating-point
12362 arithmetic" (Version 0.19) http://mpmath.org/
12364 Examples
12365 --------
12366 >>> import numpy as np
12367 >>> import matplotlib.pyplot as plt
12368 >>> from scipy.special import shichi, sici
12370 `shichi` accepts real or complex input:
12372 >>> shichi(0.5)
12373 (0.5069967498196671, -0.05277684495649357)
12374 >>> shichi(0.5 + 2.5j)
12375 ((0.11772029666668238+1.831091777729851j),
12376 (0.29912435887648825+1.7395351121166562j))
12378 The hyperbolic sine and cosine integrals Shi(z) and Chi(z) are
12379 related to the sine and cosine integrals Si(z) and Ci(z) by
12381 * Shi(z) = -i*Si(i*z)
12382 * Chi(z) = Ci(-i*z) + i*pi/2
12384 >>> z = 0.25 + 5j
12385 >>> shi, chi = shichi(z)
12386 >>> shi, -1j*sici(1j*z)[0] # Should be the same.
12387 ((-0.04834719325101729+1.5469354086921228j),
12388 (-0.04834719325101729+1.5469354086921228j))
12389 >>> chi, sici(-1j*z)[1] + 1j*np.pi/2 # Should be the same.
12390 ((-0.19568708973868087+1.556276312103824j),
12391 (-0.19568708973868087+1.556276312103824j))
12393 Plot the functions evaluated on the real axis:
12395 >>> xp = np.geomspace(1e-8, 4.0, 250)
12396 >>> x = np.concatenate((-xp[::-1], xp))
12397 >>> shi, chi = shichi(x)
12399 >>> fig, ax = plt.subplots()
12400 >>> ax.plot(x, shi, label='Shi(x)')
12401 >>> ax.plot(x, chi, '--', label='Chi(x)')
12402 >>> ax.set_xlabel('x')
12403 >>> ax.set_title('Hyperbolic Sine and Cosine Integrals')
12404 >>> ax.legend(shadow=True, framealpha=1, loc='lower right')
12405 >>> ax.grid(True)
12406 >>> plt.show()
12408 """)
12410add_newdoc("sici",
12411 r"""
12412 sici(x, out=None)
12414 Sine and cosine integrals.
12416 The sine integral is
12418 .. math::
12420 \int_0^x \frac{\sin{t}}{t}dt
12422 and the cosine integral is
12424 .. math::
12426 \gamma + \log(x) + \int_0^x \frac{\cos{t} - 1}{t}dt
12428 where :math:`\gamma` is Euler's constant and :math:`\log` is the
12429 principal branch of the logarithm [1]_.
12431 Parameters
12432 ----------
12433 x : array_like
12434 Real or complex points at which to compute the sine and cosine
12435 integrals.
12436 out : tuple of ndarray, optional
12437 Optional output arrays for the function results
12439 Returns
12440 -------
12441 si : scalar or ndarray
12442 Sine integral at ``x``
12443 ci : scalar or ndarray
12444 Cosine integral at ``x``
12446 See Also
12447 --------
12448 shichi : Hyperbolic sine and cosine integrals.
12449 exp1 : Exponential integral E1.
12450 expi : Exponential integral Ei.
12452 Notes
12453 -----
12454 For real arguments with ``x < 0``, ``ci`` is the real part of the
12455 cosine integral. For such points ``ci(x)`` and ``ci(x + 0j)``
12456 differ by a factor of ``1j*pi``.
12458 For real arguments the function is computed by calling Cephes'
12459 [2]_ *sici* routine. For complex arguments the algorithm is based
12460 on Mpmath's [3]_ *si* and *ci* routines.
12462 References
12463 ----------
12464 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
12465 Handbook of Mathematical Functions with Formulas,
12466 Graphs, and Mathematical Tables. New York: Dover, 1972.
12467 (See Section 5.2.)
12468 .. [2] Cephes Mathematical Functions Library,
12469 http://www.netlib.org/cephes/
12470 .. [3] Fredrik Johansson and others.
12471 "mpmath: a Python library for arbitrary-precision floating-point
12472 arithmetic" (Version 0.19) http://mpmath.org/
12474 Examples
12475 --------
12476 >>> import numpy as np
12477 >>> import matplotlib.pyplot as plt
12478 >>> from scipy.special import sici, exp1
12480 `sici` accepts real or complex input:
12482 >>> sici(2.5)
12483 (1.7785201734438267, 0.2858711963653835)
12484 >>> sici(2.5 + 3j)
12485 ((4.505735874563953+0.06863305018999577j),
12486 (0.0793644206906966-2.935510262937543j))
12488 For z in the right half plane, the sine and cosine integrals are
12489 related to the exponential integral E1 (implemented in SciPy as
12490 `scipy.special.exp1`) by
12492 * Si(z) = (E1(i*z) - E1(-i*z))/2i + pi/2
12493 * Ci(z) = -(E1(i*z) + E1(-i*z))/2
12495 See [1]_ (equations 5.2.21 and 5.2.23).
12497 We can verify these relations:
12499 >>> z = 2 - 3j
12500 >>> sici(z)
12501 ((4.54751388956229-1.3991965806460565j),
12502 (1.408292501520851+2.9836177420296055j))
12504 >>> (exp1(1j*z) - exp1(-1j*z))/2j + np.pi/2 # Same as sine integral
12505 (4.54751388956229-1.3991965806460565j)
12507 >>> -(exp1(1j*z) + exp1(-1j*z))/2 # Same as cosine integral
12508 (1.408292501520851+2.9836177420296055j)
12510 Plot the functions evaluated on the real axis; the dotted horizontal
12511 lines are at pi/2 and -pi/2:
12513 >>> x = np.linspace(-16, 16, 150)
12514 >>> si, ci = sici(x)
12516 >>> fig, ax = plt.subplots()
12517 >>> ax.plot(x, si, label='Si(x)')
12518 >>> ax.plot(x, ci, '--', label='Ci(x)')
12519 >>> ax.legend(shadow=True, framealpha=1, loc='upper left')
12520 >>> ax.set_xlabel('x')
12521 >>> ax.set_title('Sine and Cosine Integrals')
12522 >>> ax.axhline(np.pi/2, linestyle=':', alpha=0.5, color='k')
12523 >>> ax.axhline(-np.pi/2, linestyle=':', alpha=0.5, color='k')
12524 >>> ax.grid(True)
12525 >>> plt.show()
12527 """)
12529add_newdoc("sindg",
12530 """
12531 sindg(x, out=None)
12533 Sine of the angle `x` given in degrees.
12535 Parameters
12536 ----------
12537 x : array_like
12538 Angle, given in degrees.
12539 out : ndarray, optional
12540 Optional output array for the function results.
12542 Returns
12543 -------
12544 scalar or ndarray
12545 Sine at the input.
12547 See Also
12548 --------
12549 cosdg, tandg, cotdg
12551 Examples
12552 --------
12553 >>> import numpy as np
12554 >>> import scipy.special as sc
12556 It is more accurate than using sine directly.
12558 >>> x = 180 * np.arange(3)
12559 >>> sc.sindg(x)
12560 array([ 0., -0., 0.])
12561 >>> np.sin(x * np.pi / 180)
12562 array([ 0.0000000e+00, 1.2246468e-16, -2.4492936e-16])
12564 """)
12566add_newdoc("smirnov",
12567 r"""
12568 smirnov(n, d, out=None)
12570 Kolmogorov-Smirnov complementary cumulative distribution function
12572 Returns the exact Kolmogorov-Smirnov complementary cumulative
12573 distribution function,(aka the Survival Function) of Dn+ (or Dn-)
12574 for a one-sided test of equality between an empirical and a
12575 theoretical distribution. It is equal to the probability that the
12576 maximum difference between a theoretical distribution and an empirical
12577 one based on `n` samples is greater than d.
12579 Parameters
12580 ----------
12581 n : int
12582 Number of samples
12583 d : float array_like
12584 Deviation between the Empirical CDF (ECDF) and the target CDF.
12585 out : ndarray, optional
12586 Optional output array for the function results
12588 Returns
12589 -------
12590 scalar or ndarray
12591 The value(s) of smirnov(n, d), Prob(Dn+ >= d) (Also Prob(Dn- >= d))
12593 See Also
12594 --------
12595 smirnovi : The Inverse Survival Function for the distribution
12596 scipy.stats.ksone : Provides the functionality as a continuous distribution
12597 kolmogorov, kolmogi : Functions for the two-sided distribution
12599 Notes
12600 -----
12601 `smirnov` is used by `stats.kstest` in the application of the
12602 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
12603 function is exposed in `scpy.special`, but the recommended way to achieve
12604 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
12605 `stats.ksone` distribution.
12607 Examples
12608 --------
12609 >>> import numpy as np
12610 >>> from scipy.special import smirnov
12611 >>> from scipy.stats import norm
12613 Show the probability of a gap at least as big as 0, 0.5 and 1.0 for a
12614 sample of size 5.
12616 >>> smirnov(5, [0, 0.5, 1.0])
12617 array([ 1. , 0.056, 0. ])
12619 Compare a sample of size 5 against N(0, 1), the standard normal
12620 distribution with mean 0 and standard deviation 1.
12622 `x` is the sample.
12624 >>> x = np.array([-1.392, -0.135, 0.114, 0.190, 1.82])
12626 >>> target = norm(0, 1)
12627 >>> cdfs = target.cdf(x)
12628 >>> cdfs
12629 array([0.0819612 , 0.44630594, 0.5453811 , 0.57534543, 0.9656205 ])
12631 Construct the empirical CDF and the K-S statistics (Dn+, Dn-, Dn).
12633 >>> n = len(x)
12634 >>> ecdfs = np.arange(n+1, dtype=float)/n
12635 >>> cols = np.column_stack([x, ecdfs[1:], cdfs, cdfs - ecdfs[:n],
12636 ... ecdfs[1:] - cdfs])
12637 >>> with np.printoptions(precision=3):
12638 ... print(cols)
12639 [[-1.392 0.2 0.082 0.082 0.118]
12640 [-0.135 0.4 0.446 0.246 -0.046]
12641 [ 0.114 0.6 0.545 0.145 0.055]
12642 [ 0.19 0.8 0.575 -0.025 0.225]
12643 [ 1.82 1. 0.966 0.166 0.034]]
12644 >>> gaps = cols[:, -2:]
12645 >>> Dnpm = np.max(gaps, axis=0)
12646 >>> print(f'Dn-={Dnpm[0]:f}, Dn+={Dnpm[1]:f}')
12647 Dn-=0.246306, Dn+=0.224655
12648 >>> probs = smirnov(n, Dnpm)
12649 >>> print(f'For a sample of size {n} drawn from N(0, 1):',
12650 ... f' Smirnov n={n}: Prob(Dn- >= {Dnpm[0]:f}) = {probs[0]:.4f}',
12651 ... f' Smirnov n={n}: Prob(Dn+ >= {Dnpm[1]:f}) = {probs[1]:.4f}',
12652 ... sep='\n')
12653 For a sample of size 5 drawn from N(0, 1):
12654 Smirnov n=5: Prob(Dn- >= 0.246306) = 0.4711
12655 Smirnov n=5: Prob(Dn+ >= 0.224655) = 0.5245
12657 Plot the empirical CDF and the standard normal CDF.
12659 >>> import matplotlib.pyplot as plt
12660 >>> plt.step(np.concatenate(([-2.5], x, [2.5])),
12661 ... np.concatenate((ecdfs, [1])),
12662 ... where='post', label='Empirical CDF')
12663 >>> xx = np.linspace(-2.5, 2.5, 100)
12664 >>> plt.plot(xx, target.cdf(xx), '--', label='CDF for N(0, 1)')
12666 Add vertical lines marking Dn+ and Dn-.
12668 >>> iminus, iplus = np.argmax(gaps, axis=0)
12669 >>> plt.vlines([x[iminus]], ecdfs[iminus], cdfs[iminus], color='r',
12670 ... alpha=0.5, lw=4)
12671 >>> plt.vlines([x[iplus]], cdfs[iplus], ecdfs[iplus+1], color='m',
12672 ... alpha=0.5, lw=4)
12674 >>> plt.grid(True)
12675 >>> plt.legend(framealpha=1, shadow=True)
12676 >>> plt.show()
12677 """)
12679add_newdoc("smirnovi",
12680 """
12681 smirnovi(n, p, out=None)
12683 Inverse to `smirnov`
12685 Returns `d` such that ``smirnov(n, d) == p``, the critical value
12686 corresponding to `p`.
12688 Parameters
12689 ----------
12690 n : int
12691 Number of samples
12692 p : float array_like
12693 Probability
12694 out : ndarray, optional
12695 Optional output array for the function results
12697 Returns
12698 -------
12699 scalar or ndarray
12700 The value(s) of smirnovi(n, p), the critical values.
12702 See Also
12703 --------
12704 smirnov : The Survival Function (SF) for the distribution
12705 scipy.stats.ksone : Provides the functionality as a continuous distribution
12706 kolmogorov, kolmogi : Functions for the two-sided distribution
12707 scipy.stats.kstwobign : Two-sided Kolmogorov-Smirnov distribution, large n
12709 Notes
12710 -----
12711 `smirnov` is used by `stats.kstest` in the application of the
12712 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
12713 function is exposed in `scpy.special`, but the recommended way to achieve
12714 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
12715 `stats.ksone` distribution.
12717 Examples
12718 --------
12719 >>> from scipy.special import smirnovi, smirnov
12721 >>> n = 24
12722 >>> deviations = [0.1, 0.2, 0.3]
12724 Use `smirnov` to compute the complementary CDF of the Smirnov
12725 distribution for the given number of samples and deviations.
12727 >>> p = smirnov(n, deviations)
12728 >>> p
12729 array([0.58105083, 0.12826832, 0.01032231])
12731 The inverse function ``smirnovi(n, p)`` returns ``deviations``.
12733 >>> smirnovi(n, p)
12734 array([0.1, 0.2, 0.3])
12736 """)
12738add_newdoc("_smirnovc",
12739 """
12740 _smirnovc(n, d)
12741 Internal function, do not use.
12742 """)
12744add_newdoc("_smirnovci",
12745 """
12746 Internal function, do not use.
12747 """)
12749add_newdoc("_smirnovp",
12750 """
12751 _smirnovp(n, p)
12752 Internal function, do not use.
12753 """)
12755add_newdoc("spence",
12756 r"""
12757 spence(z, out=None)
12759 Spence's function, also known as the dilogarithm.
12761 It is defined to be
12763 .. math::
12764 \int_1^z \frac{\log(t)}{1 - t}dt
12766 for complex :math:`z`, where the contour of integration is taken
12767 to avoid the branch cut of the logarithm. Spence's function is
12768 analytic everywhere except the negative real axis where it has a
12769 branch cut.
12771 Parameters
12772 ----------
12773 z : array_like
12774 Points at which to evaluate Spence's function
12775 out : ndarray, optional
12776 Optional output array for the function results
12778 Returns
12779 -------
12780 s : scalar or ndarray
12781 Computed values of Spence's function
12783 Notes
12784 -----
12785 There is a different convention which defines Spence's function by
12786 the integral
12788 .. math::
12789 -\int_0^z \frac{\log(1 - t)}{t}dt;
12791 this is our ``spence(1 - z)``.
12793 Examples
12794 --------
12795 >>> import numpy as np
12796 >>> from scipy.special import spence
12797 >>> import matplotlib.pyplot as plt
12799 The function is defined for complex inputs:
12801 >>> spence([1-1j, 1.5+2j, 3j, -10-5j])
12802 array([-0.20561676+0.91596559j, -0.86766909-1.39560134j,
12803 -0.59422064-2.49129918j, -1.14044398+6.80075924j])
12805 For complex inputs on the branch cut, which is the negative real axis,
12806 the function returns the limit for ``z`` with positive imaginary part.
12807 For example, in the following, note the sign change of the imaginary
12808 part of the output for ``z = -2`` and ``z = -2 - 1e-8j``:
12810 >>> spence([-2 + 1e-8j, -2, -2 - 1e-8j])
12811 array([2.32018041-3.45139229j, 2.32018042-3.4513923j ,
12812 2.32018041+3.45139229j])
12814 The function returns ``nan`` for real inputs on the branch cut:
12816 >>> spence(-1.5)
12817 nan
12819 Verify some particular values: ``spence(0) = pi**2/6``,
12820 ``spence(1) = 0`` and ``spence(2) = -pi**2/12``.
12822 >>> spence([0, 1, 2])
12823 array([ 1.64493407, 0. , -0.82246703])
12824 >>> np.pi**2/6, -np.pi**2/12
12825 (1.6449340668482264, -0.8224670334241132)
12827 Verify the identity::
12829 spence(z) + spence(1 - z) = pi**2/6 - log(z)*log(1 - z)
12831 >>> z = 3 + 4j
12832 >>> spence(z) + spence(1 - z)
12833 (-2.6523186143876067+1.8853470951513935j)
12834 >>> np.pi**2/6 - np.log(z)*np.log(1 - z)
12835 (-2.652318614387606+1.885347095151394j)
12837 Plot the function for positive real input.
12839 >>> fig, ax = plt.subplots()
12840 >>> x = np.linspace(0, 6, 400)
12841 >>> ax.plot(x, spence(x))
12842 >>> ax.grid()
12843 >>> ax.set_xlabel('x')
12844 >>> ax.set_title('spence(x)')
12845 >>> plt.show()
12846 """)
12848add_newdoc(
12849 "stdtr",
12850 r"""
12851 stdtr(df, t, out=None)
12853 Student t distribution cumulative distribution function
12855 Returns the integral:
12857 .. math::
12858 \frac{\Gamma((df+1)/2)}{\sqrt{\pi df} \Gamma(df/2)}
12859 \int_{-\infty}^t (1+x^2/df)^{-(df+1)/2}\, dx
12861 Parameters
12862 ----------
12863 df : array_like
12864 Degrees of freedom
12865 t : array_like
12866 Upper bound of the integral
12867 out : ndarray, optional
12868 Optional output array for the function results
12870 Returns
12871 -------
12872 scalar or ndarray
12873 Value of the Student t CDF at t
12875 See Also
12876 --------
12877 stdtridf : inverse of stdtr with respect to `df`
12878 stdtrit : inverse of stdtr with respect to `t`
12879 scipy.stats.t : student t distribution
12881 Notes
12882 -----
12883 The student t distribution is also available as `scipy.stats.t`.
12884 Calling `stdtr` directly can improve performance compared to the
12885 ``cdf`` method of `scipy.stats.t` (see last example below).
12887 Examples
12888 --------
12889 Calculate the function for ``df=3`` at ``t=1``.
12891 >>> import numpy as np
12892 >>> from scipy.special import stdtr
12893 >>> import matplotlib.pyplot as plt
12894 >>> stdtr(3, 1)
12895 0.8044988905221148
12897 Plot the function for three different degrees of freedom.
12899 >>> x = np.linspace(-10, 10, 1000)
12900 >>> fig, ax = plt.subplots()
12901 >>> parameters = [(1, "solid"), (3, "dashed"), (10, "dotted")]
12902 >>> for (df, linestyle) in parameters:
12903 ... ax.plot(x, stdtr(df, x), ls=linestyle, label=f"$df={df}$")
12904 >>> ax.legend()
12905 >>> ax.set_title("Student t distribution cumulative distribution function")
12906 >>> plt.show()
12908 The function can be computed for several degrees of freedom at the same
12909 time by providing a NumPy array or list for `df`:
12911 >>> stdtr([1, 2, 3], 1)
12912 array([0.75 , 0.78867513, 0.80449889])
12914 It is possible to calculate the function at several points for several
12915 different degrees of freedom simultaneously by providing arrays for `df`
12916 and `t` with shapes compatible for broadcasting. Compute `stdtr` at
12917 4 points for 3 degrees of freedom resulting in an array of shape 3x4.
12919 >>> dfs = np.array([[1], [2], [3]])
12920 >>> t = np.array([2, 4, 6, 8])
12921 >>> dfs.shape, t.shape
12922 ((3, 1), (4,))
12924 >>> stdtr(dfs, t)
12925 array([[0.85241638, 0.92202087, 0.94743154, 0.96041658],
12926 [0.90824829, 0.97140452, 0.98666426, 0.99236596],
12927 [0.93033702, 0.98599577, 0.99536364, 0.99796171]])
12929 The t distribution is also available as `scipy.stats.t`. Calling `stdtr`
12930 directly can be much faster than calling the ``cdf`` method of
12931 `scipy.stats.t`. To get the same results, one must use the following
12932 parametrization: ``scipy.stats.t(df).cdf(x) = stdtr(df, x)``.
12934 >>> from scipy.stats import t
12935 >>> df, x = 3, 1
12936 >>> stdtr_result = stdtr(df, x) # this can be faster than below
12937 >>> stats_result = t(df).cdf(x)
12938 >>> stats_result == stdtr_result # test that results are equal
12939 True
12940 """)
12942add_newdoc("stdtridf",
12943 """
12944 stdtridf(p, t, out=None)
12946 Inverse of `stdtr` vs df
12948 Returns the argument df such that stdtr(df, t) is equal to `p`.
12950 Parameters
12951 ----------
12952 p : array_like
12953 Probability
12954 t : array_like
12955 Upper bound of the integral
12956 out : ndarray, optional
12957 Optional output array for the function results
12959 Returns
12960 -------
12961 df : scalar or ndarray
12962 Value of `df` such that ``stdtr(df, t) == p``
12964 See Also
12965 --------
12966 stdtr : Student t CDF
12967 stdtrit : inverse of stdtr with respect to `t`
12968 scipy.stats.t : Student t distribution
12970 Examples
12971 --------
12972 Compute the student t cumulative distribution function for one
12973 parameter set.
12975 >>> from scipy.special import stdtr, stdtridf
12976 >>> df, x = 5, 2
12977 >>> cdf_value = stdtr(df, x)
12978 >>> cdf_value
12979 0.9490302605850709
12981 Verify that `stdtridf` recovers the original value for `df` given
12982 the CDF value and `x`.
12984 >>> stdtridf(cdf_value, x)
12985 5.0
12986 """)
12988add_newdoc("stdtrit",
12989 """
12990 stdtrit(df, p, out=None)
12992 The `p`-th quantile of the student t distribution.
12994 This function is the inverse of the student t distribution cumulative
12995 distribution function (CDF), returning `t` such that `stdtr(df, t) = p`.
12997 Returns the argument `t` such that stdtr(df, t) is equal to `p`.
12999 Parameters
13000 ----------
13001 df : array_like
13002 Degrees of freedom
13003 p : array_like
13004 Probability
13005 out : ndarray, optional
13006 Optional output array for the function results
13008 Returns
13009 -------
13010 t : scalar or ndarray
13011 Value of `t` such that ``stdtr(df, t) == p``
13013 See Also
13014 --------
13015 stdtr : Student t CDF
13016 stdtridf : inverse of stdtr with respect to `df`
13017 scipy.stats.t : Student t distribution
13019 Notes
13020 -----
13021 The student t distribution is also available as `scipy.stats.t`. Calling
13022 `stdtrit` directly can improve performance compared to the ``ppf``
13023 method of `scipy.stats.t` (see last example below).
13025 Examples
13026 --------
13027 `stdtrit` represents the inverse of the student t distribution CDF which
13028 is available as `stdtr`. Here, we calculate the CDF for ``df`` at
13029 ``x=1``. `stdtrit` then returns ``1`` up to floating point errors
13030 given the same value for `df` and the computed CDF value.
13032 >>> import numpy as np
13033 >>> from scipy.special import stdtr, stdtrit
13034 >>> import matplotlib.pyplot as plt
13035 >>> df = 3
13036 >>> x = 1
13037 >>> cdf_value = stdtr(df, x)
13038 >>> stdtrit(df, cdf_value)
13039 0.9999999994418539
13041 Plot the function for three different degrees of freedom.
13043 >>> x = np.linspace(0, 1, 1000)
13044 >>> parameters = [(1, "solid"), (2, "dashed"), (5, "dotted")]
13045 >>> fig, ax = plt.subplots()
13046 >>> for (df, linestyle) in parameters:
13047 ... ax.plot(x, stdtrit(df, x), ls=linestyle, label=f"$df={df}$")
13048 >>> ax.legend()
13049 >>> ax.set_ylim(-10, 10)
13050 >>> ax.set_title("Student t distribution quantile function")
13051 >>> plt.show()
13053 The function can be computed for several degrees of freedom at the same
13054 time by providing a NumPy array or list for `df`:
13056 >>> stdtrit([1, 2, 3], 0.7)
13057 array([0.72654253, 0.6172134 , 0.58438973])
13059 It is possible to calculate the function at several points for several
13060 different degrees of freedom simultaneously by providing arrays for `df`
13061 and `p` with shapes compatible for broadcasting. Compute `stdtrit` at
13062 4 points for 3 degrees of freedom resulting in an array of shape 3x4.
13064 >>> dfs = np.array([[1], [2], [3]])
13065 >>> p = np.array([0.2, 0.4, 0.7, 0.8])
13066 >>> dfs.shape, p.shape
13067 ((3, 1), (4,))
13069 >>> stdtrit(dfs, p)
13070 array([[-1.37638192, -0.3249197 , 0.72654253, 1.37638192],
13071 [-1.06066017, -0.28867513, 0.6172134 , 1.06066017],
13072 [-0.97847231, -0.27667066, 0.58438973, 0.97847231]])
13074 The t distribution is also available as `scipy.stats.t`. Calling `stdtrit`
13075 directly can be much faster than calling the ``ppf`` method of
13076 `scipy.stats.t`. To get the same results, one must use the following
13077 parametrization: ``scipy.stats.t(df).ppf(x) = stdtrit(df, x)``.
13079 >>> from scipy.stats import t
13080 >>> df, x = 3, 0.5
13081 >>> stdtrit_result = stdtrit(df, x) # this can be faster than below
13082 >>> stats_result = t(df).ppf(x)
13083 >>> stats_result == stdtrit_result # test that results are equal
13084 True
13085 """)
13087add_newdoc("struve",
13088 r"""
13089 struve(v, x, out=None)
13091 Struve function.
13093 Return the value of the Struve function of order `v` at `x`. The Struve
13094 function is defined as,
13096 .. math::
13097 H_v(x) = (z/2)^{v + 1} \sum_{n=0}^\infty \frac{(-1)^n (z/2)^{2n}}{\Gamma(n + \frac{3}{2}) \Gamma(n + v + \frac{3}{2})},
13099 where :math:`\Gamma` is the gamma function.
13101 Parameters
13102 ----------
13103 v : array_like
13104 Order of the Struve function (float).
13105 x : array_like
13106 Argument of the Struve function (float; must be positive unless `v` is
13107 an integer).
13108 out : ndarray, optional
13109 Optional output array for the function results
13111 Returns
13112 -------
13113 H : scalar or ndarray
13114 Value of the Struve function of order `v` at `x`.
13116 Notes
13117 -----
13118 Three methods discussed in [1]_ are used to evaluate the Struve function:
13120 - power series
13121 - expansion in Bessel functions (if :math:`|z| < |v| + 20`)
13122 - asymptotic large-z expansion (if :math:`z \geq 0.7v + 12`)
13124 Rounding errors are estimated based on the largest terms in the sums, and
13125 the result associated with the smallest error is returned.
13127 See also
13128 --------
13129 modstruve: Modified Struve function
13131 References
13132 ----------
13133 .. [1] NIST Digital Library of Mathematical Functions
13134 https://dlmf.nist.gov/11
13136 Examples
13137 --------
13138 Calculate the Struve function of order 1 at 2.
13140 >>> import numpy as np
13141 >>> from scipy.special import struve
13142 >>> import matplotlib.pyplot as plt
13143 >>> struve(1, 2.)
13144 0.6467637282835622
13146 Calculate the Struve function at 2 for orders 1, 2 and 3 by providing
13147 a list for the order parameter `v`.
13149 >>> struve([1, 2, 3], 2.)
13150 array([0.64676373, 0.28031806, 0.08363767])
13152 Calculate the Struve function of order 1 for several points by providing
13153 an array for `x`.
13155 >>> points = np.array([2., 5., 8.])
13156 >>> struve(1, points)
13157 array([0.64676373, 0.80781195, 0.48811605])
13159 Compute the Struve function for several orders at several points by
13160 providing arrays for `v` and `z`. The arrays have to be broadcastable
13161 to the correct shapes.
13163 >>> orders = np.array([[1], [2], [3]])
13164 >>> points.shape, orders.shape
13165 ((3,), (3, 1))
13167 >>> struve(orders, points)
13168 array([[0.64676373, 0.80781195, 0.48811605],
13169 [0.28031806, 1.56937455, 1.51769363],
13170 [0.08363767, 1.50872065, 2.98697513]])
13172 Plot the Struve functions of order 0 to 3 from -10 to 10.
13174 >>> fig, ax = plt.subplots()
13175 >>> x = np.linspace(-10., 10., 1000)
13176 >>> for i in range(4):
13177 ... ax.plot(x, struve(i, x), label=f'$H_{i!r}$')
13178 >>> ax.legend(ncol=2)
13179 >>> ax.set_xlim(-10, 10)
13180 >>> ax.set_title(r"Struve functions $H_{\nu}$")
13181 >>> plt.show()
13182 """)
13184add_newdoc("tandg",
13185 """
13186 tandg(x, out=None)
13188 Tangent of angle `x` given in degrees.
13190 Parameters
13191 ----------
13192 x : array_like
13193 Angle, given in degrees.
13194 out : ndarray, optional
13195 Optional output array for the function results.
13197 Returns
13198 -------
13199 scalar or ndarray
13200 Tangent at the input.
13202 See Also
13203 --------
13204 sindg, cosdg, cotdg
13206 Examples
13207 --------
13208 >>> import numpy as np
13209 >>> import scipy.special as sc
13211 It is more accurate than using tangent directly.
13213 >>> x = 180 * np.arange(3)
13214 >>> sc.tandg(x)
13215 array([0., 0., 0.])
13216 >>> np.tan(x * np.pi / 180)
13217 array([ 0.0000000e+00, -1.2246468e-16, -2.4492936e-16])
13219 """)
13221add_newdoc(
13222 "tklmbda",
13223 r"""
13224 tklmbda(x, lmbda, out=None)
13226 Cumulative distribution function of the Tukey lambda distribution.
13228 Parameters
13229 ----------
13230 x, lmbda : array_like
13231 Parameters
13232 out : ndarray, optional
13233 Optional output array for the function results
13235 Returns
13236 -------
13237 cdf : scalar or ndarray
13238 Value of the Tukey lambda CDF
13240 See Also
13241 --------
13242 scipy.stats.tukeylambda : Tukey lambda distribution
13244 Examples
13245 --------
13246 >>> import numpy as np
13247 >>> import matplotlib.pyplot as plt
13248 >>> from scipy.special import tklmbda, expit
13250 Compute the cumulative distribution function (CDF) of the Tukey lambda
13251 distribution at several ``x`` values for `lmbda` = -1.5.
13253 >>> x = np.linspace(-2, 2, 9)
13254 >>> x
13255 array([-2. , -1.5, -1. , -0.5, 0. , 0.5, 1. , 1.5, 2. ])
13256 >>> tklmbda(x, -1.5)
13257 array([0.34688734, 0.3786554 , 0.41528805, 0.45629737, 0.5 ,
13258 0.54370263, 0.58471195, 0.6213446 , 0.65311266])
13260 When `lmbda` is 0, the function is the logistic sigmoid function,
13261 which is implemented in `scipy.special` as `expit`.
13263 >>> tklmbda(x, 0)
13264 array([0.11920292, 0.18242552, 0.26894142, 0.37754067, 0.5 ,
13265 0.62245933, 0.73105858, 0.81757448, 0.88079708])
13266 >>> expit(x)
13267 array([0.11920292, 0.18242552, 0.26894142, 0.37754067, 0.5 ,
13268 0.62245933, 0.73105858, 0.81757448, 0.88079708])
13270 When `lmbda` is 1, the Tukey lambda distribution is uniform on the
13271 interval [-1, 1], so the CDF increases linearly.
13273 >>> t = np.linspace(-1, 1, 9)
13274 >>> tklmbda(t, 1)
13275 array([0. , 0.125, 0.25 , 0.375, 0.5 , 0.625, 0.75 , 0.875, 1. ])
13277 In the following, we generate plots for several values of `lmbda`.
13279 The first figure shows graphs for `lmbda` <= 0.
13281 >>> styles = ['-', '-.', '--', ':']
13282 >>> fig, ax = plt.subplots()
13283 >>> x = np.linspace(-12, 12, 500)
13284 >>> for k, lmbda in enumerate([-1.0, -0.5, 0.0]):
13285 ... y = tklmbda(x, lmbda)
13286 ... ax.plot(x, y, styles[k], label=f'$\lambda$ = {lmbda:-4.1f}')
13288 >>> ax.set_title('tklmbda(x, $\lambda$)')
13289 >>> ax.set_label('x')
13290 >>> ax.legend(framealpha=1, shadow=True)
13291 >>> ax.grid(True)
13293 The second figure shows graphs for `lmbda` > 0. The dots in the
13294 graphs show the bounds of the support of the distribution.
13296 >>> fig, ax = plt.subplots()
13297 >>> x = np.linspace(-4.2, 4.2, 500)
13298 >>> lmbdas = [0.25, 0.5, 1.0, 1.5]
13299 >>> for k, lmbda in enumerate(lmbdas):
13300 ... y = tklmbda(x, lmbda)
13301 ... ax.plot(x, y, styles[k], label=f'$\lambda$ = {lmbda}')
13303 >>> ax.set_prop_cycle(None)
13304 >>> for lmbda in lmbdas:
13305 ... ax.plot([-1/lmbda, 1/lmbda], [0, 1], '.', ms=8)
13307 >>> ax.set_title('tklmbda(x, $\lambda$)')
13308 >>> ax.set_xlabel('x')
13309 >>> ax.legend(framealpha=1, shadow=True)
13310 >>> ax.grid(True)
13312 >>> plt.tight_layout()
13313 >>> plt.show()
13315 The CDF of the Tukey lambda distribution is also implemented as the
13316 ``cdf`` method of `scipy.stats.tukeylambda`. In the following,
13317 ``tukeylambda.cdf(x, -0.5)`` and ``tklmbda(x, -0.5)`` compute the
13318 same values:
13320 >>> from scipy.stats import tukeylambda
13321 >>> x = np.linspace(-2, 2, 9)
13323 >>> tukeylambda.cdf(x, -0.5)
13324 array([0.21995157, 0.27093858, 0.33541677, 0.41328161, 0.5 ,
13325 0.58671839, 0.66458323, 0.72906142, 0.78004843])
13327 >>> tklmbda(x, -0.5)
13328 array([0.21995157, 0.27093858, 0.33541677, 0.41328161, 0.5 ,
13329 0.58671839, 0.66458323, 0.72906142, 0.78004843])
13331 The implementation in ``tukeylambda`` also provides location and scale
13332 parameters, and other methods such as ``pdf()`` (the probability
13333 density function) and ``ppf()`` (the inverse of the CDF), so for
13334 working with the Tukey lambda distribution, ``tukeylambda`` is more
13335 generally useful. The primary advantage of ``tklmbda`` is that it is
13336 significantly faster than ``tukeylambda.cdf``.
13337 """)
13339add_newdoc("wofz",
13340 """
13341 wofz(z, out=None)
13343 Faddeeva function
13345 Returns the value of the Faddeeva function for complex argument::
13347 exp(-z**2) * erfc(-i*z)
13349 Parameters
13350 ----------
13351 z : array_like
13352 complex argument
13353 out : ndarray, optional
13354 Optional output array for the function results
13356 Returns
13357 -------
13358 scalar or ndarray
13359 Value of the Faddeeva function
13361 See Also
13362 --------
13363 dawsn, erf, erfc, erfcx, erfi
13365 References
13366 ----------
13367 .. [1] Steven G. Johnson, Faddeeva W function implementation.
13368 http://ab-initio.mit.edu/Faddeeva
13370 Examples
13371 --------
13372 >>> import numpy as np
13373 >>> from scipy import special
13374 >>> import matplotlib.pyplot as plt
13376 >>> x = np.linspace(-3, 3)
13377 >>> z = special.wofz(x)
13379 >>> plt.plot(x, z.real, label='wofz(x).real')
13380 >>> plt.plot(x, z.imag, label='wofz(x).imag')
13381 >>> plt.xlabel('$x$')
13382 >>> plt.legend(framealpha=1, shadow=True)
13383 >>> plt.grid(alpha=0.25)
13384 >>> plt.show()
13386 """)
13388add_newdoc("xlogy",
13389 """
13390 xlogy(x, y, out=None)
13392 Compute ``x*log(y)`` so that the result is 0 if ``x = 0``.
13394 Parameters
13395 ----------
13396 x : array_like
13397 Multiplier
13398 y : array_like
13399 Argument
13400 out : ndarray, optional
13401 Optional output array for the function results
13403 Returns
13404 -------
13405 z : scalar or ndarray
13406 Computed x*log(y)
13408 Notes
13409 -----
13410 The log function used in the computation is the natural log.
13412 .. versionadded:: 0.13.0
13414 Examples
13415 --------
13416 We can use this function to calculate the binary logistic loss also
13417 known as the binary cross entropy. This loss function is used for
13418 binary classification problems and is defined as:
13420 .. math::
13421 L = 1/n * \\sum_{i=0}^n -(y_i*log(y\\_pred_i) + (1-y_i)*log(1-y\\_pred_i))
13423 We can define the parameters `x` and `y` as y and y_pred respectively.
13424 y is the array of the actual labels which over here can be either 0 or 1.
13425 y_pred is the array of the predicted probabilities with respect to
13426 the positive class (1).
13428 >>> import numpy as np
13429 >>> from scipy.special import xlogy
13430 >>> y = np.array([0, 1, 0, 1, 1, 0])
13431 >>> y_pred = np.array([0.3, 0.8, 0.4, 0.7, 0.9, 0.2])
13432 >>> n = len(y)
13433 >>> loss = -(xlogy(y, y_pred) + xlogy(1 - y, 1 - y_pred)).sum()
13434 >>> loss /= n
13435 >>> loss
13436 0.29597052165495025
13438 A lower loss is usually better as it indicates that the predictions are
13439 similar to the actual labels. In this example since our predicted
13440 probabilties are close to the actual labels, we get an overall loss
13441 that is reasonably low and appropriate.
13443 """)
13445add_newdoc("xlog1py",
13446 """
13447 xlog1py(x, y, out=None)
13449 Compute ``x*log1p(y)`` so that the result is 0 if ``x = 0``.
13451 Parameters
13452 ----------
13453 x : array_like
13454 Multiplier
13455 y : array_like
13456 Argument
13457 out : ndarray, optional
13458 Optional output array for the function results
13460 Returns
13461 -------
13462 z : scalar or ndarray
13463 Computed x*log1p(y)
13465 Notes
13466 -----
13468 .. versionadded:: 0.13.0
13470 Examples
13471 --------
13472 This example shows how the function can be used to calculate the log of
13473 the probability mass function for a geometric discrete random variable.
13474 The probability mass function of the geometric distribution is defined
13475 as follows:
13477 .. math:: f(k) = (1-p)^{k-1} p
13479 where :math:`p` is the probability of a single success
13480 and :math:`1-p` is the probability of a single failure
13481 and :math:`k` is the number of trials to get the first success.
13483 >>> import numpy as np
13484 >>> from scipy.special import xlog1py
13485 >>> p = 0.5
13486 >>> k = 100
13487 >>> _pmf = np.power(1 - p, k - 1) * p
13488 >>> _pmf
13489 7.888609052210118e-31
13491 If we take k as a relatively large number the value of the probability
13492 mass function can become very low. In such cases taking the log of the
13493 pmf would be more suitable as the log function can change the values
13494 to a scale that is more appropriate to work with.
13496 >>> _log_pmf = xlog1py(k - 1, -p) + np.log(p)
13497 >>> _log_pmf
13498 -69.31471805599453
13500 We can confirm that we get a value close to the original pmf value by
13501 taking the exponential of the log pmf.
13503 >>> _orig_pmf = np.exp(_log_pmf)
13504 >>> np.isclose(_pmf, _orig_pmf)
13505 True
13507 """)
13509add_newdoc("y0",
13510 r"""
13511 y0(x, out=None)
13513 Bessel function of the second kind of order 0.
13515 Parameters
13516 ----------
13517 x : array_like
13518 Argument (float).
13519 out : ndarray, optional
13520 Optional output array for the function results
13522 Returns
13523 -------
13524 Y : scalar or ndarray
13525 Value of the Bessel function of the second kind of order 0 at `x`.
13527 Notes
13528 -----
13530 The domain is divided into the intervals [0, 5] and (5, infinity). In the
13531 first interval a rational approximation :math:`R(x)` is employed to
13532 compute,
13534 .. math::
13536 Y_0(x) = R(x) + \frac{2 \log(x) J_0(x)}{\pi},
13538 where :math:`J_0` is the Bessel function of the first kind of order 0.
13540 In the second interval, the Hankel asymptotic expansion is employed with
13541 two rational functions of degree 6/6 and 7/7.
13543 This function is a wrapper for the Cephes [1]_ routine `y0`.
13545 See also
13546 --------
13547 j0: Bessel function of the first kind of order 0
13548 yv: Bessel function of the first kind
13550 References
13551 ----------
13552 .. [1] Cephes Mathematical Functions Library,
13553 http://www.netlib.org/cephes/
13555 Examples
13556 --------
13557 Calculate the function at one point:
13559 >>> from scipy.special import y0
13560 >>> y0(1.)
13561 0.08825696421567697
13563 Calculate at several points:
13565 >>> import numpy as np
13566 >>> y0(np.array([0.5, 2., 3.]))
13567 array([-0.44451873, 0.51037567, 0.37685001])
13569 Plot the function from 0 to 10.
13571 >>> import matplotlib.pyplot as plt
13572 >>> fig, ax = plt.subplots()
13573 >>> x = np.linspace(0., 10., 1000)
13574 >>> y = y0(x)
13575 >>> ax.plot(x, y)
13576 >>> plt.show()
13578 """)
13580add_newdoc("y1",
13581 """
13582 y1(x, out=None)
13584 Bessel function of the second kind of order 1.
13586 Parameters
13587 ----------
13588 x : array_like
13589 Argument (float).
13590 out : ndarray, optional
13591 Optional output array for the function results
13593 Returns
13594 -------
13595 Y : scalar or ndarray
13596 Value of the Bessel function of the second kind of order 1 at `x`.
13598 Notes
13599 -----
13601 The domain is divided into the intervals [0, 8] and (8, infinity). In the
13602 first interval a 25 term Chebyshev expansion is used, and computing
13603 :math:`J_1` (the Bessel function of the first kind) is required. In the
13604 second, the asymptotic trigonometric representation is employed using two
13605 rational functions of degree 5/5.
13607 This function is a wrapper for the Cephes [1]_ routine `y1`.
13609 See also
13610 --------
13611 j1: Bessel function of the first kind of order 1
13612 yn: Bessel function of the second kind
13613 yv: Bessel function of the second kind
13615 References
13616 ----------
13617 .. [1] Cephes Mathematical Functions Library,
13618 http://www.netlib.org/cephes/
13620 Examples
13621 --------
13622 Calculate the function at one point:
13624 >>> from scipy.special import y1
13625 >>> y1(1.)
13626 -0.7812128213002888
13628 Calculate at several points:
13630 >>> import numpy as np
13631 >>> y1(np.array([0.5, 2., 3.]))
13632 array([-1.47147239, -0.10703243, 0.32467442])
13634 Plot the function from 0 to 10.
13636 >>> import matplotlib.pyplot as plt
13637 >>> fig, ax = plt.subplots()
13638 >>> x = np.linspace(0., 10., 1000)
13639 >>> y = y1(x)
13640 >>> ax.plot(x, y)
13641 >>> plt.show()
13643 """)
13645add_newdoc("yn",
13646 r"""
13647 yn(n, x, out=None)
13649 Bessel function of the second kind of integer order and real argument.
13651 Parameters
13652 ----------
13653 n : array_like
13654 Order (integer).
13655 x : array_like
13656 Argument (float).
13657 out : ndarray, optional
13658 Optional output array for the function results
13660 Returns
13661 -------
13662 Y : scalar or ndarray
13663 Value of the Bessel function, :math:`Y_n(x)`.
13665 Notes
13666 -----
13667 Wrapper for the Cephes [1]_ routine `yn`.
13669 The function is evaluated by forward recurrence on `n`, starting with
13670 values computed by the Cephes routines `y0` and `y1`. If `n = 0` or 1,
13671 the routine for `y0` or `y1` is called directly.
13673 See also
13674 --------
13675 yv : For real order and real or complex argument.
13676 y0: faster implementation of this function for order 0
13677 y1: faster implementation of this function for order 1
13679 References
13680 ----------
13681 .. [1] Cephes Mathematical Functions Library,
13682 http://www.netlib.org/cephes/
13684 Examples
13685 --------
13686 Evaluate the function of order 0 at one point.
13688 >>> from scipy.special import yn
13689 >>> yn(0, 1.)
13690 0.08825696421567697
13692 Evaluate the function at one point for different orders.
13694 >>> yn(0, 1.), yn(1, 1.), yn(2, 1.)
13695 (0.08825696421567697, -0.7812128213002888, -1.6506826068162546)
13697 The evaluation for different orders can be carried out in one call by
13698 providing a list or NumPy array as argument for the `v` parameter:
13700 >>> yn([0, 1, 2], 1.)
13701 array([ 0.08825696, -0.78121282, -1.65068261])
13703 Evaluate the function at several points for order 0 by providing an
13704 array for `z`.
13706 >>> import numpy as np
13707 >>> points = np.array([0.5, 3., 8.])
13708 >>> yn(0, points)
13709 array([-0.44451873, 0.37685001, 0.22352149])
13711 If `z` is an array, the order parameter `v` must be broadcastable to
13712 the correct shape if different orders shall be computed in one call.
13713 To calculate the orders 0 and 1 for an 1D array:
13715 >>> orders = np.array([[0], [1]])
13716 >>> orders.shape
13717 (2, 1)
13719 >>> yn(orders, points)
13720 array([[-0.44451873, 0.37685001, 0.22352149],
13721 [-1.47147239, 0.32467442, -0.15806046]])
13723 Plot the functions of order 0 to 3 from 0 to 10.
13725 >>> import matplotlib.pyplot as plt
13726 >>> fig, ax = plt.subplots()
13727 >>> x = np.linspace(0., 10., 1000)
13728 >>> for i in range(4):
13729 ... ax.plot(x, yn(i, x), label=f'$Y_{i!r}$')
13730 >>> ax.set_ylim(-3, 1)
13731 >>> ax.legend()
13732 >>> plt.show()
13733 """)
13735add_newdoc("yv",
13736 r"""
13737 yv(v, z, out=None)
13739 Bessel function of the second kind of real order and complex argument.
13741 Parameters
13742 ----------
13743 v : array_like
13744 Order (float).
13745 z : array_like
13746 Argument (float or complex).
13747 out : ndarray, optional
13748 Optional output array for the function results
13750 Returns
13751 -------
13752 Y : scalar or ndarray
13753 Value of the Bessel function of the second kind, :math:`Y_v(x)`.
13755 Notes
13756 -----
13757 For positive `v` values, the computation is carried out using the
13758 AMOS [1]_ `zbesy` routine, which exploits the connection to the Hankel
13759 Bessel functions :math:`H_v^{(1)}` and :math:`H_v^{(2)}`,
13761 .. math:: Y_v(z) = \frac{1}{2\imath} (H_v^{(1)} - H_v^{(2)}).
13763 For negative `v` values the formula,
13765 .. math:: Y_{-v}(z) = Y_v(z) \cos(\pi v) + J_v(z) \sin(\pi v)
13767 is used, where :math:`J_v(z)` is the Bessel function of the first kind,
13768 computed using the AMOS routine `zbesj`. Note that the second term is
13769 exactly zero for integer `v`; to improve accuracy the second term is
13770 explicitly omitted for `v` values such that `v = floor(v)`.
13772 See also
13773 --------
13774 yve : :math:`Y_v` with leading exponential behavior stripped off.
13775 y0: faster implementation of this function for order 0
13776 y1: faster implementation of this function for order 1
13778 References
13779 ----------
13780 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
13781 of a Complex Argument and Nonnegative Order",
13782 http://netlib.org/amos/
13784 Examples
13785 --------
13786 Evaluate the function of order 0 at one point.
13788 >>> from scipy.special import yv
13789 >>> yv(0, 1.)
13790 0.088256964215677
13792 Evaluate the function at one point for different orders.
13794 >>> yv(0, 1.), yv(1, 1.), yv(1.5, 1.)
13795 (0.088256964215677, -0.7812128213002889, -1.102495575160179)
13797 The evaluation for different orders can be carried out in one call by
13798 providing a list or NumPy array as argument for the `v` parameter:
13800 >>> yv([0, 1, 1.5], 1.)
13801 array([ 0.08825696, -0.78121282, -1.10249558])
13803 Evaluate the function at several points for order 0 by providing an
13804 array for `z`.
13806 >>> import numpy as np
13807 >>> points = np.array([0.5, 3., 8.])
13808 >>> yv(0, points)
13809 array([-0.44451873, 0.37685001, 0.22352149])
13811 If `z` is an array, the order parameter `v` must be broadcastable to
13812 the correct shape if different orders shall be computed in one call.
13813 To calculate the orders 0 and 1 for an 1D array:
13815 >>> orders = np.array([[0], [1]])
13816 >>> orders.shape
13817 (2, 1)
13819 >>> yv(orders, points)
13820 array([[-0.44451873, 0.37685001, 0.22352149],
13821 [-1.47147239, 0.32467442, -0.15806046]])
13823 Plot the functions of order 0 to 3 from 0 to 10.
13825 >>> import matplotlib.pyplot as plt
13826 >>> fig, ax = plt.subplots()
13827 >>> x = np.linspace(0., 10., 1000)
13828 >>> for i in range(4):
13829 ... ax.plot(x, yv(i, x), label=f'$Y_{i!r}$')
13830 >>> ax.set_ylim(-3, 1)
13831 >>> ax.legend()
13832 >>> plt.show()
13834 """)
13836add_newdoc("yve",
13837 r"""
13838 yve(v, z, out=None)
13840 Exponentially scaled Bessel function of the second kind of real order.
13842 Returns the exponentially scaled Bessel function of the second
13843 kind of real order `v` at complex `z`::
13845 yve(v, z) = yv(v, z) * exp(-abs(z.imag))
13847 Parameters
13848 ----------
13849 v : array_like
13850 Order (float).
13851 z : array_like
13852 Argument (float or complex).
13853 out : ndarray, optional
13854 Optional output array for the function results
13856 Returns
13857 -------
13858 Y : scalar or ndarray
13859 Value of the exponentially scaled Bessel function.
13861 See Also
13862 --------
13863 yv: Unscaled Bessel function of the second kind of real order.
13865 Notes
13866 -----
13867 For positive `v` values, the computation is carried out using the
13868 AMOS [1]_ `zbesy` routine, which exploits the connection to the Hankel
13869 Bessel functions :math:`H_v^{(1)}` and :math:`H_v^{(2)}`,
13871 .. math:: Y_v(z) = \frac{1}{2\imath} (H_v^{(1)} - H_v^{(2)}).
13873 For negative `v` values the formula,
13875 .. math:: Y_{-v}(z) = Y_v(z) \cos(\pi v) + J_v(z) \sin(\pi v)
13877 is used, where :math:`J_v(z)` is the Bessel function of the first kind,
13878 computed using the AMOS routine `zbesj`. Note that the second term is
13879 exactly zero for integer `v`; to improve accuracy the second term is
13880 explicitly omitted for `v` values such that `v = floor(v)`.
13882 Exponentially scaled Bessel functions are useful for large `z`:
13883 for these, the unscaled Bessel functions can easily under-or overflow.
13885 References
13886 ----------
13887 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
13888 of a Complex Argument and Nonnegative Order",
13889 http://netlib.org/amos/
13891 Examples
13892 --------
13893 Compare the output of `yv` and `yve` for large complex arguments for `z`
13894 by computing their values for order ``v=1`` at ``z=1000j``. We see that
13895 `yv` returns nan but `yve` returns a finite number:
13897 >>> import numpy as np
13898 >>> from scipy.special import yv, yve
13899 >>> v = 1
13900 >>> z = 1000j
13901 >>> yv(v, z), yve(v, z)
13902 ((nan+nanj), (-0.012610930256928629+7.721967686709076e-19j))
13904 For real arguments for `z`, `yve` returns the same as `yv` up to
13905 floating point errors.
13907 >>> v, z = 1, 1000
13908 >>> yv(v, z), yve(v, z)
13909 (-0.02478433129235178, -0.02478433129235179)
13911 The function can be evaluated for several orders at the same time by
13912 providing a list or NumPy array for `v`:
13914 >>> yve([1, 2, 3], 1j)
13915 array([-0.20791042+0.14096627j, 0.38053618-0.04993878j,
13916 0.00815531-1.66311097j])
13918 In the same way, the function can be evaluated at several points in one
13919 call by providing a list or NumPy array for `z`:
13921 >>> yve(1, np.array([1j, 2j, 3j]))
13922 array([-0.20791042+0.14096627j, -0.21526929+0.01205044j,
13923 -0.19682671+0.00127278j])
13925 It is also possible to evaluate several orders at several points
13926 at the same time by providing arrays for `v` and `z` with
13927 broadcasting compatible shapes. Compute `yve` for two different orders
13928 `v` and three points `z` resulting in a 2x3 array.
13930 >>> v = np.array([[1], [2]])
13931 >>> z = np.array([3j, 4j, 5j])
13932 >>> v.shape, z.shape
13933 ((2, 1), (3,))
13935 >>> yve(v, z)
13936 array([[-1.96826713e-01+1.27277544e-03j, -1.78750840e-01+1.45558819e-04j,
13937 -1.63972267e-01+1.73494110e-05j],
13938 [1.94960056e-03-1.11782545e-01j, 2.02902325e-04-1.17626501e-01j,
13939 2.27727687e-05-1.17951906e-01j]])
13940 """)
13942add_newdoc("_zeta",
13943 """
13944 _zeta(x, q)
13946 Internal function, Hurwitz zeta.
13948 """)
13950add_newdoc("zetac",
13951 """
13952 zetac(x, out=None)
13954 Riemann zeta function minus 1.
13956 This function is defined as
13958 .. math:: \\zeta(x) = \\sum_{k=2}^{\\infty} 1 / k^x,
13960 where ``x > 1``. For ``x < 1`` the analytic continuation is
13961 computed. For more information on the Riemann zeta function, see
13962 [dlmf]_.
13964 Parameters
13965 ----------
13966 x : array_like of float
13967 Values at which to compute zeta(x) - 1 (must be real).
13968 out : ndarray, optional
13969 Optional output array for the function results
13971 Returns
13972 -------
13973 scalar or ndarray
13974 Values of zeta(x) - 1.
13976 See Also
13977 --------
13978 zeta
13980 Examples
13981 --------
13982 >>> import numpy as np
13983 >>> from scipy.special import zetac, zeta
13985 Some special values:
13987 >>> zetac(2), np.pi**2/6 - 1
13988 (0.64493406684822641, 0.6449340668482264)
13990 >>> zetac(-1), -1.0/12 - 1
13991 (-1.0833333333333333, -1.0833333333333333)
13993 Compare ``zetac(x)`` to ``zeta(x) - 1`` for large `x`:
13995 >>> zetac(60), zeta(60) - 1
13996 (8.673617380119933e-19, 0.0)
13998 References
13999 ----------
14000 .. [dlmf] NIST Digital Library of Mathematical Functions
14001 https://dlmf.nist.gov/25
14003 """)
14005add_newdoc("_riemann_zeta",
14006 """
14007 Internal function, use `zeta` instead.
14008 """)
14010add_newdoc("_struve_asymp_large_z",
14011 """
14012 _struve_asymp_large_z(v, z, is_h)
14014 Internal function for testing `struve` & `modstruve`
14016 Evaluates using asymptotic expansion
14018 Returns
14019 -------
14020 v, err
14021 """)
14023add_newdoc("_struve_power_series",
14024 """
14025 _struve_power_series(v, z, is_h)
14027 Internal function for testing `struve` & `modstruve`
14029 Evaluates using power series
14031 Returns
14032 -------
14033 v, err
14034 """)
14036add_newdoc("_struve_bessel_series",
14037 """
14038 _struve_bessel_series(v, z, is_h)
14040 Internal function for testing `struve` & `modstruve`
14042 Evaluates using Bessel function series
14044 Returns
14045 -------
14046 v, err
14047 """)
14049add_newdoc("_spherical_jn",
14050 """
14051 Internal function, use `spherical_jn` instead.
14052 """)
14054add_newdoc("_spherical_jn_d",
14055 """
14056 Internal function, use `spherical_jn` instead.
14057 """)
14059add_newdoc("_spherical_yn",
14060 """
14061 Internal function, use `spherical_yn` instead.
14062 """)
14064add_newdoc("_spherical_yn_d",
14065 """
14066 Internal function, use `spherical_yn` instead.
14067 """)
14069add_newdoc("_spherical_in",
14070 """
14071 Internal function, use `spherical_in` instead.
14072 """)
14074add_newdoc("_spherical_in_d",
14075 """
14076 Internal function, use `spherical_in` instead.
14077 """)
14079add_newdoc("_spherical_kn",
14080 """
14081 Internal function, use `spherical_kn` instead.
14082 """)
14084add_newdoc("_spherical_kn_d",
14085 """
14086 Internal function, use `spherical_kn` instead.
14087 """)
14089add_newdoc("loggamma",
14090 r"""
14091 loggamma(z, out=None)
14093 Principal branch of the logarithm of the gamma function.
14095 Defined to be :math:`\log(\Gamma(x))` for :math:`x > 0` and
14096 extended to the complex plane by analytic continuation. The
14097 function has a single branch cut on the negative real axis.
14099 .. versionadded:: 0.18.0
14101 Parameters
14102 ----------
14103 z : array_like
14104 Values in the complex plane at which to compute ``loggamma``
14105 out : ndarray, optional
14106 Output array for computed values of ``loggamma``
14108 Returns
14109 -------
14110 loggamma : scalar or ndarray
14111 Values of ``loggamma`` at z.
14113 Notes
14114 -----
14115 It is not generally true that :math:`\log\Gamma(z) =
14116 \log(\Gamma(z))`, though the real parts of the functions do
14117 agree. The benefit of not defining `loggamma` as
14118 :math:`\log(\Gamma(z))` is that the latter function has a
14119 complicated branch cut structure whereas `loggamma` is analytic
14120 except for on the negative real axis.
14122 The identities
14124 .. math::
14125 \exp(\log\Gamma(z)) &= \Gamma(z) \\
14126 \log\Gamma(z + 1) &= \log(z) + \log\Gamma(z)
14128 make `loggamma` useful for working in complex logspace.
14130 On the real line `loggamma` is related to `gammaln` via
14131 ``exp(loggamma(x + 0j)) = gammasgn(x)*exp(gammaln(x))``, up to
14132 rounding error.
14134 The implementation here is based on [hare1997]_.
14136 See also
14137 --------
14138 gammaln : logarithm of the absolute value of the gamma function
14139 gammasgn : sign of the gamma function
14141 References
14142 ----------
14143 .. [hare1997] D.E.G. Hare,
14144 *Computing the Principal Branch of log-Gamma*,
14145 Journal of Algorithms, Volume 25, Issue 2, November 1997, pages 221-236.
14146 """)
14148add_newdoc("_sinpi",
14149 """
14150 Internal function, do not use.
14151 """)
14153add_newdoc("_cospi",
14154 """
14155 Internal function, do not use.
14156 """)
14158add_newdoc("owens_t",
14159 """
14160 owens_t(h, a, out=None)
14162 Owen's T Function.
14164 The function T(h, a) gives the probability of the event
14165 (X > h and 0 < Y < a * X) where X and Y are independent
14166 standard normal random variables.
14168 Parameters
14169 ----------
14170 h: array_like
14171 Input value.
14172 a: array_like
14173 Input value.
14174 out : ndarray, optional
14175 Optional output array for the function results
14177 Returns
14178 -------
14179 t: scalar or ndarray
14180 Probability of the event (X > h and 0 < Y < a * X),
14181 where X and Y are independent standard normal random variables.
14183 Examples
14184 --------
14185 >>> from scipy import special
14186 >>> a = 3.5
14187 >>> h = 0.78
14188 >>> special.owens_t(h, a)
14189 0.10877216734852274
14191 References
14192 ----------
14193 .. [1] M. Patefield and D. Tandy, "Fast and accurate calculation of
14194 Owen's T Function", Statistical Software vol. 5, pp. 1-25, 2000.
14195 """)
14197add_newdoc("_factorial",
14198 """
14199 Internal function, do not use.
14200 """)
14202add_newdoc("wright_bessel",
14203 r"""
14204 wright_bessel(a, b, x, out=None)
14206 Wright's generalized Bessel function.
14208 Wright's generalized Bessel function is an entire function and defined as
14210 .. math:: \Phi(a, b; x) = \sum_{k=0}^\infty \frac{x^k}{k! \Gamma(a k + b)}
14212 See also [1].
14214 Parameters
14215 ----------
14216 a : array_like of float
14217 a >= 0
14218 b : array_like of float
14219 b >= 0
14220 x : array_like of float
14221 x >= 0
14222 out : ndarray, optional
14223 Optional output array for the function results
14225 Returns
14226 -------
14227 scalar or ndarray
14228 Value of the Wright's generalized Bessel function
14230 Notes
14231 -----
14232 Due to the compexity of the function with its three parameters, only
14233 non-negative arguments are implemented.
14235 Examples
14236 --------
14237 >>> from scipy.special import wright_bessel
14238 >>> a, b, x = 1.5, 1.1, 2.5
14239 >>> wright_bessel(a, b-1, x)
14240 4.5314465939443025
14242 Now, let us verify the relation
14244 .. math:: \Phi(a, b-1; x) = a x \Phi(a, b+a; x) + (b-1) \Phi(a, b; x)
14246 >>> a * x * wright_bessel(a, b+a, x) + (b-1) * wright_bessel(a, b, x)
14247 4.5314465939443025
14249 References
14250 ----------
14251 .. [1] Digital Library of Mathematical Functions, 10.46.
14252 https://dlmf.nist.gov/10.46.E1
14253 """)
14256add_newdoc("ndtri_exp",
14257 r"""
14258 ndtri_exp(y, out=None)
14260 Inverse of `log_ndtr` vs x. Allows for greater precision than
14261 `ndtri` composed with `numpy.exp` for very small values of y and for
14262 y close to 0.
14264 Parameters
14265 ----------
14266 y : array_like of float
14267 Function argument
14268 out : ndarray, optional
14269 Optional output array for the function results
14271 Returns
14272 -------
14273 scalar or ndarray
14274 Inverse of the log CDF of the standard normal distribution, evaluated
14275 at y.
14277 Examples
14278 --------
14279 >>> import numpy as np
14280 >>> import scipy.special as sc
14282 `ndtri_exp` agrees with the naive implementation when the latter does
14283 not suffer from underflow.
14285 >>> sc.ndtri_exp(-1)
14286 -0.33747496376420244
14287 >>> sc.ndtri(np.exp(-1))
14288 -0.33747496376420244
14290 For extreme values of y, the naive approach fails
14292 >>> sc.ndtri(np.exp(-800))
14293 -inf
14294 >>> sc.ndtri(np.exp(-1e-20))
14295 inf
14297 whereas `ndtri_exp` is still able to compute the result to high precision.
14299 >>> sc.ndtri_exp(-800)
14300 -39.88469483825668
14301 >>> sc.ndtri_exp(-1e-20)
14302 9.262340089798409
14304 See Also
14305 --------
14306 log_ndtr, ndtri, ndtr
14307 """)