Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/special/_add_newdocs.py: 99%
269 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-12 06:31 +0000
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.
9from typing import Dict
11docdict: Dict[str, str] = {}
14def get(name):
15 return docdict.get(name)
18def add_newdoc(name, doc):
19 docdict[name] = doc
22add_newdoc("_sf_error_test_function",
23 """
24 Private function; do not use.
25 """)
28add_newdoc("_cosine_cdf",
29 """
30 _cosine_cdf(x)
32 Cumulative distribution function (CDF) of the cosine distribution::
34 { 0, x < -pi
35 cdf(x) = { (pi + x + sin(x))/(2*pi), -pi <= x <= pi
36 { 1, x > pi
38 Parameters
39 ----------
40 x : array_like
41 `x` must contain real numbers.
43 Returns
44 -------
45 scalar or ndarray
46 The cosine distribution CDF evaluated at `x`.
48 """)
50add_newdoc("_cosine_invcdf",
51 """
52 _cosine_invcdf(p)
54 Inverse of the cumulative distribution function (CDF) of the cosine
55 distribution.
57 The CDF of the cosine distribution is::
59 cdf(x) = (pi + x + sin(x))/(2*pi)
61 This function computes the inverse of cdf(x).
63 Parameters
64 ----------
65 p : array_like
66 `p` must contain real numbers in the interval ``0 <= p <= 1``.
67 `nan` is returned for values of `p` outside the interval [0, 1].
69 Returns
70 -------
71 scalar or ndarray
72 The inverse of the cosine distribution CDF evaluated at `p`.
74 """)
76add_newdoc("sph_harm",
77 r"""
78 sph_harm(m, n, theta, phi, out=None)
80 Compute spherical harmonics.
82 The spherical harmonics are defined as
84 .. math::
86 Y^m_n(\theta,\phi) = \sqrt{\frac{2n+1}{4\pi} \frac{(n-m)!}{(n+m)!}}
87 e^{i m \theta} P^m_n(\cos(\phi))
89 where :math:`P_n^m` are the associated Legendre functions; see `lpmv`.
91 Parameters
92 ----------
93 m : array_like
94 Order of the harmonic (int); must have ``|m| <= n``.
95 n : array_like
96 Degree of the harmonic (int); must have ``n >= 0``. This is
97 often denoted by ``l`` (lower case L) in descriptions of
98 spherical harmonics.
99 theta : array_like
100 Azimuthal (longitudinal) coordinate; must be in ``[0, 2*pi]``.
101 phi : array_like
102 Polar (colatitudinal) coordinate; must be in ``[0, pi]``.
103 out : ndarray, optional
104 Optional output array for the function values
106 Returns
107 -------
108 y_mn : complex scalar or ndarray
109 The harmonic :math:`Y^m_n` sampled at ``theta`` and ``phi``.
111 Notes
112 -----
113 There are different conventions for the meanings of the input
114 arguments ``theta`` and ``phi``. In SciPy ``theta`` is the
115 azimuthal angle and ``phi`` is the polar angle. It is common to
116 see the opposite convention, that is, ``theta`` as the polar angle
117 and ``phi`` as the azimuthal angle.
119 Note that SciPy's spherical harmonics include the Condon-Shortley
120 phase [2]_ because it is part of `lpmv`.
122 With SciPy's conventions, the first several spherical harmonics
123 are
125 .. math::
127 Y_0^0(\theta, \phi) &= \frac{1}{2} \sqrt{\frac{1}{\pi}} \\
128 Y_1^{-1}(\theta, \phi) &= \frac{1}{2} \sqrt{\frac{3}{2\pi}}
129 e^{-i\theta} \sin(\phi) \\
130 Y_1^0(\theta, \phi) &= \frac{1}{2} \sqrt{\frac{3}{\pi}}
131 \cos(\phi) \\
132 Y_1^1(\theta, \phi) &= -\frac{1}{2} \sqrt{\frac{3}{2\pi}}
133 e^{i\theta} \sin(\phi).
135 References
136 ----------
137 .. [1] Digital Library of Mathematical Functions, 14.30.
138 https://dlmf.nist.gov/14.30
139 .. [2] https://en.wikipedia.org/wiki/Spherical_harmonics#Condon.E2.80.93Shortley_phase
140 """)
142add_newdoc("_ellip_harm",
143 """
144 Internal function, use `ellip_harm` instead.
145 """)
147add_newdoc("_ellip_norm",
148 """
149 Internal function, use `ellip_norm` instead.
150 """)
152add_newdoc("_lambertw",
153 """
154 Internal function, use `lambertw` instead.
155 """)
157add_newdoc("voigt_profile",
158 r"""
159 voigt_profile(x, sigma, gamma, out=None)
161 Voigt profile.
163 The Voigt profile is a convolution of a 1-D Normal distribution with
164 standard deviation ``sigma`` and a 1-D Cauchy distribution with half-width at
165 half-maximum ``gamma``.
167 If ``sigma = 0``, PDF of Cauchy distribution is returned.
168 Conversely, if ``gamma = 0``, PDF of Normal distribution is returned.
169 If ``sigma = gamma = 0``, the return value is ``Inf`` for ``x = 0``, and ``0`` for all other ``x``.
171 Parameters
172 ----------
173 x : array_like
174 Real argument
175 sigma : array_like
176 The standard deviation of the Normal distribution part
177 gamma : array_like
178 The half-width at half-maximum of the Cauchy distribution part
179 out : ndarray, optional
180 Optional output array for the function values
182 Returns
183 -------
184 scalar or ndarray
185 The Voigt profile at the given arguments
187 Notes
188 -----
189 It can be expressed in terms of Faddeeva function
191 .. math:: V(x; \sigma, \gamma) = \frac{Re[w(z)]}{\sigma\sqrt{2\pi}},
192 .. math:: z = \frac{x + i\gamma}{\sqrt{2}\sigma}
194 where :math:`w(z)` is the Faddeeva function.
196 See Also
197 --------
198 wofz : Faddeeva function
200 References
201 ----------
202 .. [1] https://en.wikipedia.org/wiki/Voigt_profile
204 Examples
205 --------
206 Calculate the function at point 2 for ``sigma=1`` and ``gamma=1``.
208 >>> from scipy.special import voigt_profile
209 >>> import numpy as np
210 >>> import matplotlib.pyplot as plt
211 >>> voigt_profile(2, 1., 1.)
212 0.09071519942627544
214 Calculate the function at several points by providing a NumPy array
215 for `x`.
217 >>> values = np.array([-2., 0., 5])
218 >>> voigt_profile(values, 1., 1.)
219 array([0.0907152 , 0.20870928, 0.01388492])
221 Plot the function for different parameter sets.
223 >>> fig, ax = plt.subplots(figsize=(8, 8))
224 >>> x = np.linspace(-10, 10, 500)
225 >>> parameters_list = [(1.5, 0., "solid"), (1.3, 0.5, "dashed"),
226 ... (0., 1.8, "dotted"), (1., 1., "dashdot")]
227 >>> for params in parameters_list:
228 ... sigma, gamma, linestyle = params
229 ... voigt = voigt_profile(x, sigma, gamma)
230 ... ax.plot(x, voigt, label=rf"$\sigma={sigma},\, \gamma={gamma}$",
231 ... ls=linestyle)
232 >>> ax.legend()
233 >>> plt.show()
235 Verify visually that the Voigt profile indeed arises as the convolution
236 of a normal and a Cauchy distribution.
238 >>> from scipy.signal import convolve
239 >>> x, dx = np.linspace(-10, 10, 500, retstep=True)
240 >>> def gaussian(x, sigma):
241 ... return np.exp(-0.5 * x**2/sigma**2)/(sigma * np.sqrt(2*np.pi))
242 >>> def cauchy(x, gamma):
243 ... return gamma/(np.pi * (np.square(x)+gamma**2))
244 >>> sigma = 2
245 >>> gamma = 1
246 >>> gauss_profile = gaussian(x, sigma)
247 >>> cauchy_profile = cauchy(x, gamma)
248 >>> convolved = dx * convolve(cauchy_profile, gauss_profile, mode="same")
249 >>> voigt = voigt_profile(x, sigma, gamma)
250 >>> fig, ax = plt.subplots(figsize=(8, 8))
251 >>> ax.plot(x, gauss_profile, label="Gauss: $G$", c='b')
252 >>> ax.plot(x, cauchy_profile, label="Cauchy: $C$", c='y', ls="dashed")
253 >>> xx = 0.5*(x[1:] + x[:-1]) # midpoints
254 >>> ax.plot(xx, convolved[1:], label="Convolution: $G * C$", ls='dashdot',
255 ... c='k')
256 >>> ax.plot(x, voigt, label="Voigt", ls='dotted', c='r')
257 >>> ax.legend()
258 >>> plt.show()
259 """)
261add_newdoc("wrightomega",
262 r"""
263 wrightomega(z, out=None)
265 Wright Omega function.
267 Defined as the solution to
269 .. math::
271 \omega + \log(\omega) = z
273 where :math:`\log` is the principal branch of the complex logarithm.
275 Parameters
276 ----------
277 z : array_like
278 Points at which to evaluate the Wright Omega function
279 out : ndarray, optional
280 Optional output array for the function values
282 Returns
283 -------
284 omega : scalar or ndarray
285 Values of the Wright Omega function
287 Notes
288 -----
289 .. versionadded:: 0.19.0
291 The function can also be defined as
293 .. math::
295 \omega(z) = W_{K(z)}(e^z)
297 where :math:`K(z) = \lceil (\Im(z) - \pi)/(2\pi) \rceil` is the
298 unwinding number and :math:`W` is the Lambert W function.
300 The implementation here is taken from [1]_.
302 See Also
303 --------
304 lambertw : The Lambert W function
306 References
307 ----------
308 .. [1] Lawrence, Corless, and Jeffrey, "Algorithm 917: Complex
309 Double-Precision Evaluation of the Wright :math:`\omega`
310 Function." ACM Transactions on Mathematical Software,
311 2012. :doi:`10.1145/2168773.2168779`.
313 Examples
314 --------
315 >>> import numpy as np
316 >>> from scipy.special import wrightomega, lambertw
318 >>> wrightomega([-2, -1, 0, 1, 2])
319 array([0.12002824, 0.27846454, 0.56714329, 1. , 1.5571456 ])
321 Complex input:
323 >>> wrightomega(3 + 5j)
324 (1.5804428632097158+3.8213626783287937j)
326 Verify that ``wrightomega(z)`` satisfies ``w + log(w) = z``:
328 >>> w = -5 + 4j
329 >>> wrightomega(w + np.log(w))
330 (-5+4j)
332 Verify the connection to ``lambertw``:
334 >>> z = 0.5 + 3j
335 >>> wrightomega(z)
336 (0.0966015889280649+1.4937828458191993j)
337 >>> lambertw(np.exp(z))
338 (0.09660158892806493+1.4937828458191993j)
340 >>> z = 0.5 + 4j
341 >>> wrightomega(z)
342 (-0.3362123489037213+2.282986001579032j)
343 >>> lambertw(np.exp(z), k=1)
344 (-0.33621234890372115+2.282986001579032j)
345 """)
348add_newdoc("agm",
349 """
350 agm(a, b, out=None)
352 Compute the arithmetic-geometric mean of `a` and `b`.
354 Start with a_0 = a and b_0 = b and iteratively compute::
356 a_{n+1} = (a_n + b_n)/2
357 b_{n+1} = sqrt(a_n*b_n)
359 a_n and b_n converge to the same limit as n increases; their common
360 limit is agm(a, b).
362 Parameters
363 ----------
364 a, b : array_like
365 Real values only. If the values are both negative, the result
366 is negative. If one value is negative and the other is positive,
367 `nan` is returned.
368 out : ndarray, optional
369 Optional output array for the function values
371 Returns
372 -------
373 scalar or ndarray
374 The arithmetic-geometric mean of `a` and `b`.
376 Examples
377 --------
378 >>> import numpy as np
379 >>> from scipy.special import agm
380 >>> a, b = 24.0, 6.0
381 >>> agm(a, b)
382 13.458171481725614
384 Compare that result to the iteration:
386 >>> while a != b:
387 ... a, b = (a + b)/2, np.sqrt(a*b)
388 ... print("a = %19.16f b=%19.16f" % (a, b))
389 ...
390 a = 15.0000000000000000 b=12.0000000000000000
391 a = 13.5000000000000000 b=13.4164078649987388
392 a = 13.4582039324993694 b=13.4581390309909850
393 a = 13.4581714817451772 b=13.4581714817060547
394 a = 13.4581714817256159 b=13.4581714817256159
396 When array-like arguments are given, broadcasting applies:
398 >>> a = np.array([[1.5], [3], [6]]) # a has shape (3, 1).
399 >>> b = np.array([6, 12, 24, 48]) # b has shape (4,).
400 >>> agm(a, b)
401 array([[ 3.36454287, 5.42363427, 9.05798751, 15.53650756],
402 [ 4.37037309, 6.72908574, 10.84726853, 18.11597502],
403 [ 6. , 8.74074619, 13.45817148, 21.69453707]])
404 """)
406add_newdoc("airy",
407 r"""
408 airy(z, out=None)
410 Airy functions and their derivatives.
412 Parameters
413 ----------
414 z : array_like
415 Real or complex argument.
416 out : tuple of ndarray, optional
417 Optional output arrays for the function values
419 Returns
420 -------
421 Ai, Aip, Bi, Bip : 4-tuple of scalar or ndarray
422 Airy functions Ai and Bi, and their derivatives Aip and Bip.
424 Notes
425 -----
426 The Airy functions Ai and Bi are two independent solutions of
428 .. math:: y''(x) = x y(x).
430 For real `z` in [-10, 10], the computation is carried out by calling
431 the Cephes [1]_ `airy` routine, which uses power series summation
432 for small `z` and rational minimax approximations for large `z`.
434 Outside this range, the AMOS [2]_ `zairy` and `zbiry` routines are
435 employed. They are computed using power series for :math:`|z| < 1` and
436 the following relations to modified Bessel functions for larger `z`
437 (where :math:`t \equiv 2 z^{3/2}/3`):
439 .. math::
441 Ai(z) = \frac{1}{\pi \sqrt{3}} K_{1/3}(t)
443 Ai'(z) = -\frac{z}{\pi \sqrt{3}} K_{2/3}(t)
445 Bi(z) = \sqrt{\frac{z}{3}} \left(I_{-1/3}(t) + I_{1/3}(t) \right)
447 Bi'(z) = \frac{z}{\sqrt{3}} \left(I_{-2/3}(t) + I_{2/3}(t)\right)
449 See also
450 --------
451 airye : exponentially scaled Airy functions.
453 References
454 ----------
455 .. [1] Cephes Mathematical Functions Library,
456 http://www.netlib.org/cephes/
457 .. [2] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
458 of a Complex Argument and Nonnegative Order",
459 http://netlib.org/amos/
461 Examples
462 --------
463 Compute the Airy functions on the interval [-15, 5].
465 >>> import numpy as np
466 >>> from scipy import special
467 >>> x = np.linspace(-15, 5, 201)
468 >>> ai, aip, bi, bip = special.airy(x)
470 Plot Ai(x) and Bi(x).
472 >>> import matplotlib.pyplot as plt
473 >>> plt.plot(x, ai, 'r', label='Ai(x)')
474 >>> plt.plot(x, bi, 'b--', label='Bi(x)')
475 >>> plt.ylim(-0.5, 1.0)
476 >>> plt.grid()
477 >>> plt.legend(loc='upper left')
478 >>> plt.show()
480 """)
482add_newdoc("airye",
483 """
484 airye(z, out=None)
486 Exponentially scaled Airy functions and their derivatives.
488 Scaling::
490 eAi = Ai * exp(2.0/3.0*z*sqrt(z))
491 eAip = Aip * exp(2.0/3.0*z*sqrt(z))
492 eBi = Bi * exp(-abs(2.0/3.0*(z*sqrt(z)).real))
493 eBip = Bip * exp(-abs(2.0/3.0*(z*sqrt(z)).real))
495 Parameters
496 ----------
497 z : array_like
498 Real or complex argument.
499 out : tuple of ndarray, optional
500 Optional output arrays for the function values
502 Returns
503 -------
504 eAi, eAip, eBi, eBip : 4-tuple of scalar or ndarray
505 Exponentially scaled Airy functions eAi and eBi, and their derivatives
506 eAip and eBip
508 Notes
509 -----
510 Wrapper for the AMOS [1]_ routines `zairy` and `zbiry`.
512 See also
513 --------
514 airy
516 References
517 ----------
518 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
519 of a Complex Argument and Nonnegative Order",
520 http://netlib.org/amos/
522 Examples
523 --------
524 We can compute exponentially scaled Airy functions and their derivatives:
526 >>> import numpy as np
527 >>> from scipy.special import airye
528 >>> import matplotlib.pyplot as plt
529 >>> z = np.linspace(0, 50, 500)
530 >>> eAi, eAip, eBi, eBip = airye(z)
531 >>> f, ax = plt.subplots(2, 1, sharex=True)
532 >>> for ind, data in enumerate([[eAi, eAip, ["eAi", "eAip"]],
533 ... [eBi, eBip, ["eBi", "eBip"]]]):
534 ... ax[ind].plot(z, data[0], "-r", z, data[1], "-b")
535 ... ax[ind].legend(data[2])
536 ... ax[ind].grid(True)
537 >>> plt.show()
539 We can compute these using usual non-scaled Airy functions by:
541 >>> from scipy.special import airy
542 >>> Ai, Aip, Bi, Bip = airy(z)
543 >>> np.allclose(eAi, Ai * np.exp(2.0 / 3.0 * z * np.sqrt(z)))
544 True
545 >>> np.allclose(eAip, Aip * np.exp(2.0 / 3.0 * z * np.sqrt(z)))
546 True
547 >>> np.allclose(eBi, Bi * np.exp(-abs(np.real(2.0 / 3.0 * z * np.sqrt(z)))))
548 True
549 >>> np.allclose(eBip, Bip * np.exp(-abs(np.real(2.0 / 3.0 * z * np.sqrt(z)))))
550 True
552 Comparing non-scaled and exponentially scaled ones, the usual non-scaled
553 function quickly underflows for large values, whereas the exponentially
554 scaled function does not.
556 >>> airy(200)
557 (0.0, 0.0, nan, nan)
558 >>> airye(200)
559 (0.07501041684381093, -1.0609012305109042, 0.15003188417418148, 2.1215836725571093)
561 """)
563add_newdoc("bdtr",
564 r"""
565 bdtr(k, n, p, out=None)
567 Binomial distribution cumulative distribution function.
569 Sum of the terms 0 through `floor(k)` of the Binomial probability density.
571 .. math::
572 \mathrm{bdtr}(k, n, p) = \sum_{j=0}^{\lfloor k \rfloor} {{n}\choose{j}} p^j (1-p)^{n-j}
574 Parameters
575 ----------
576 k : array_like
577 Number of successes (double), rounded down to the nearest integer.
578 n : array_like
579 Number of events (int).
580 p : array_like
581 Probability of success in a single event (float).
582 out : ndarray, optional
583 Optional output array for the function values
585 Returns
586 -------
587 y : scalar or ndarray
588 Probability of `floor(k)` or fewer successes in `n` independent events with
589 success probabilities of `p`.
591 Notes
592 -----
593 The terms are not summed directly; instead the regularized incomplete beta
594 function is employed, according to the formula,
596 .. math::
597 \mathrm{bdtr}(k, n, p) = I_{1 - p}(n - \lfloor k \rfloor, \lfloor k \rfloor + 1).
599 Wrapper for the Cephes [1]_ routine `bdtr`.
601 References
602 ----------
603 .. [1] Cephes Mathematical Functions Library,
604 http://www.netlib.org/cephes/
606 """)
608add_newdoc("bdtrc",
609 r"""
610 bdtrc(k, n, p, out=None)
612 Binomial distribution survival function.
614 Sum of the terms `floor(k) + 1` through `n` of the binomial probability
615 density,
617 .. math::
618 \mathrm{bdtrc}(k, n, p) = \sum_{j=\lfloor k \rfloor +1}^n {{n}\choose{j}} p^j (1-p)^{n-j}
620 Parameters
621 ----------
622 k : array_like
623 Number of successes (double), rounded down to nearest integer.
624 n : array_like
625 Number of events (int)
626 p : array_like
627 Probability of success in a single event.
628 out : ndarray, optional
629 Optional output array for the function values
631 Returns
632 -------
633 y : scalar or ndarray
634 Probability of `floor(k) + 1` or more successes in `n` independent
635 events with success probabilities of `p`.
637 See also
638 --------
639 bdtr
640 betainc
642 Notes
643 -----
644 The terms are not summed directly; instead the regularized incomplete beta
645 function is employed, according to the formula,
647 .. math::
648 \mathrm{bdtrc}(k, n, p) = I_{p}(\lfloor k \rfloor + 1, n - \lfloor k \rfloor).
650 Wrapper for the Cephes [1]_ routine `bdtrc`.
652 References
653 ----------
654 .. [1] Cephes Mathematical Functions Library,
655 http://www.netlib.org/cephes/
657 """)
659add_newdoc("bdtri",
660 r"""
661 bdtri(k, n, y, out=None)
663 Inverse function to `bdtr` with respect to `p`.
665 Finds the event probability `p` such that the sum of the terms 0 through
666 `k` of the binomial probability density is equal to the given cumulative
667 probability `y`.
669 Parameters
670 ----------
671 k : array_like
672 Number of successes (float), rounded down to the nearest integer.
673 n : array_like
674 Number of events (float)
675 y : array_like
676 Cumulative probability (probability of `k` or fewer successes in `n`
677 events).
678 out : ndarray, optional
679 Optional output array for the function values
681 Returns
682 -------
683 p : scalar or ndarray
684 The event probability such that `bdtr(\lfloor k \rfloor, n, p) = y`.
686 See also
687 --------
688 bdtr
689 betaincinv
691 Notes
692 -----
693 The computation is carried out using the inverse beta integral function
694 and the relation,::
696 1 - p = betaincinv(n - k, k + 1, y).
698 Wrapper for the Cephes [1]_ routine `bdtri`.
700 References
701 ----------
702 .. [1] Cephes Mathematical Functions Library,
703 http://www.netlib.org/cephes/
704 """)
706add_newdoc("bdtrik",
707 """
708 bdtrik(y, n, p, out=None)
710 Inverse function to `bdtr` with respect to `k`.
712 Finds the number of successes `k` such that the sum of the terms 0 through
713 `k` of the Binomial probability density for `n` events with probability
714 `p` is equal to the given cumulative probability `y`.
716 Parameters
717 ----------
718 y : array_like
719 Cumulative probability (probability of `k` or fewer successes in `n`
720 events).
721 n : array_like
722 Number of events (float).
723 p : array_like
724 Success probability (float).
725 out : ndarray, optional
726 Optional output array for the function values
728 Returns
729 -------
730 k : scalar or ndarray
731 The number of successes `k` such that `bdtr(k, n, p) = y`.
733 See also
734 --------
735 bdtr
737 Notes
738 -----
739 Formula 26.5.24 of [1]_ is used to reduce the binomial distribution to the
740 cumulative incomplete beta distribution.
742 Computation of `k` involves a search for a value that produces the desired
743 value of `y`. The search relies on the monotonicity of `y` with `k`.
745 Wrapper for the CDFLIB [2]_ Fortran routine `cdfbin`.
747 References
748 ----------
749 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
750 Handbook of Mathematical Functions with Formulas,
751 Graphs, and Mathematical Tables. New York: Dover, 1972.
752 .. [2] Barry Brown, James Lovato, and Kathy Russell,
753 CDFLIB: Library of Fortran Routines for Cumulative Distribution
754 Functions, Inverses, and Other Parameters.
756 """)
758add_newdoc("bdtrin",
759 """
760 bdtrin(k, y, p, out=None)
762 Inverse function to `bdtr` with respect to `n`.
764 Finds the number of events `n` such that the sum of the terms 0 through
765 `k` of the Binomial probability density for events with probability `p` is
766 equal to the given cumulative probability `y`.
768 Parameters
769 ----------
770 k : array_like
771 Number of successes (float).
772 y : array_like
773 Cumulative probability (probability of `k` or fewer successes in `n`
774 events).
775 p : array_like
776 Success probability (float).
777 out : ndarray, optional
778 Optional output array for the function values
780 Returns
781 -------
782 n : scalar or ndarray
783 The number of events `n` such that `bdtr(k, n, p) = y`.
785 See also
786 --------
787 bdtr
789 Notes
790 -----
791 Formula 26.5.24 of [1]_ is used to reduce the binomial distribution to the
792 cumulative incomplete beta distribution.
794 Computation of `n` involves a search for a value that produces the desired
795 value of `y`. The search relies on the monotonicity of `y` with `n`.
797 Wrapper for the CDFLIB [2]_ Fortran routine `cdfbin`.
799 References
800 ----------
801 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
802 Handbook of Mathematical Functions with Formulas,
803 Graphs, and Mathematical Tables. New York: Dover, 1972.
804 .. [2] Barry Brown, James Lovato, and Kathy Russell,
805 CDFLIB: Library of Fortran Routines for Cumulative Distribution
806 Functions, Inverses, and Other Parameters.
807 """)
809add_newdoc(
810 "binom",
811 r"""
812 binom(x, y, out=None)
814 Binomial coefficient considered as a function of two real variables.
816 For real arguments, the binomial coefficient is defined as
818 .. math::
820 \binom{x}{y} = \frac{\Gamma(x + 1)}{\Gamma(y + 1)\Gamma(x - y + 1)} =
821 \frac{1}{(x + 1)\mathrm{B}(x - y + 1, y + 1)}
823 Where :math:`\Gamma` is the Gamma function (`gamma`) and :math:`\mathrm{B}`
824 is the Beta function (`beta`) [1]_.
826 Parameters
827 ----------
828 x, y: array_like
829 Real arguments to :math:`\binom{x}{y}`.
830 out : ndarray, optional
831 Optional output array for the function values
833 Returns
834 -------
835 scalar or ndarray
836 Value of binomial coefficient.
838 See Also
839 --------
840 comb : The number of combinations of N things taken k at a time.
842 Notes
843 -----
844 The Gamma function has poles at non-positive integers and tends to either
845 positive or negative infinity depending on the direction on the real line
846 from which a pole is approached. When considered as a function of two real
847 variables, :math:`\binom{x}{y}` is thus undefined when `x` is a negative
848 integer. `binom` returns ``nan`` when ``x`` is a negative integer. This
849 is the case even when ``x`` is a negative integer and ``y`` an integer,
850 contrary to the usual convention for defining :math:`\binom{n}{k}` when it
851 is considered as a function of two integer variables.
853 References
854 ----------
855 .. [1] https://en.wikipedia.org/wiki/Binomial_coefficient
857 Examples
858 --------
859 The following examples illustrate the ways in which `binom` differs from
860 the function `comb`.
862 >>> from scipy.special import binom, comb
864 When ``exact=False`` and ``x`` and ``y`` are both positive, `comb` calls
865 `binom` internally.
867 >>> x, y = 3, 2
868 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
869 (3.0, 3.0, 3)
871 For larger values, `comb` with ``exact=True`` no longer agrees
872 with `binom`.
874 >>> x, y = 43, 23
875 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
876 (960566918219.9999, 960566918219.9999, 960566918220)
878 `binom` returns ``nan`` when ``x`` is a negative integer, but is otherwise
879 defined for negative arguments. `comb` returns 0 whenever one of ``x`` or
880 ``y`` is negative or ``x`` is less than ``y``.
882 >>> x, y = -3, 2
883 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
884 (nan, 0.0, 0)
886 >>> x, y = -3.1, 2.2
887 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
888 (18.714147876804432, 0.0, 0)
890 >>> x, y = 2.2, 3.1
891 >>> (binom(x, y), comb(x, y), comb(x, y, exact=True))
892 (0.037399983365134115, 0.0, 0)
893 """
894)
896add_newdoc("btdtria",
897 r"""
898 btdtria(p, b, x, out=None)
900 Inverse of `btdtr` with respect to `a`.
902 This is the inverse of the beta cumulative distribution function, `btdtr`,
903 considered as a function of `a`, returning the value of `a` for which
904 `btdtr(a, b, x) = p`, or
906 .. math::
907 p = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
909 Parameters
910 ----------
911 p : array_like
912 Cumulative probability, in [0, 1].
913 b : array_like
914 Shape parameter (`b` > 0).
915 x : array_like
916 The quantile, in [0, 1].
917 out : ndarray, optional
918 Optional output array for the function values
920 Returns
921 -------
922 a : scalar or ndarray
923 The value of the shape parameter `a` such that `btdtr(a, b, x) = p`.
925 See Also
926 --------
927 btdtr : Cumulative distribution function of the beta distribution.
928 btdtri : Inverse with respect to `x`.
929 btdtrib : Inverse with respect to `b`.
931 Notes
932 -----
933 Wrapper for the CDFLIB [1]_ Fortran routine `cdfbet`.
935 The cumulative distribution function `p` is computed using a routine by
936 DiDinato and Morris [2]_. Computation of `a` involves a search for a value
937 that produces the desired value of `p`. The search relies on the
938 monotonicity of `p` with `a`.
940 References
941 ----------
942 .. [1] Barry Brown, James Lovato, and Kathy Russell,
943 CDFLIB: Library of Fortran Routines for Cumulative Distribution
944 Functions, Inverses, and Other Parameters.
945 .. [2] DiDinato, A. R. and Morris, A. H.,
946 Algorithm 708: Significant Digit Computation of the Incomplete Beta
947 Function Ratios. ACM Trans. Math. Softw. 18 (1993), 360-373.
949 """)
951add_newdoc("btdtrib",
952 r"""
953 btdtria(a, p, x, out=None)
955 Inverse of `btdtr` with respect to `b`.
957 This is the inverse of the beta cumulative distribution function, `btdtr`,
958 considered as a function of `b`, returning the value of `b` for which
959 `btdtr(a, b, x) = p`, or
961 .. math::
962 p = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
964 Parameters
965 ----------
966 a : array_like
967 Shape parameter (`a` > 0).
968 p : array_like
969 Cumulative probability, in [0, 1].
970 x : array_like
971 The quantile, in [0, 1].
972 out : ndarray, optional
973 Optional output array for the function values
975 Returns
976 -------
977 b : scalar or ndarray
978 The value of the shape parameter `b` such that `btdtr(a, b, x) = p`.
980 See Also
981 --------
982 btdtr : Cumulative distribution function of the beta distribution.
983 btdtri : Inverse with respect to `x`.
984 btdtria : Inverse with respect to `a`.
986 Notes
987 -----
988 Wrapper for the CDFLIB [1]_ Fortran routine `cdfbet`.
990 The cumulative distribution function `p` is computed using a routine by
991 DiDinato and Morris [2]_. Computation of `b` involves a search for a value
992 that produces the desired value of `p`. The search relies on the
993 monotonicity of `p` with `b`.
995 References
996 ----------
997 .. [1] Barry Brown, James Lovato, and Kathy Russell,
998 CDFLIB: Library of Fortran Routines for Cumulative Distribution
999 Functions, Inverses, and Other Parameters.
1000 .. [2] DiDinato, A. R. and Morris, A. H.,
1001 Algorithm 708: Significant Digit Computation of the Incomplete Beta
1002 Function Ratios. ACM Trans. Math. Softw. 18 (1993), 360-373.
1005 """)
1007add_newdoc("bei",
1008 r"""
1009 bei(x, out=None)
1011 Kelvin function bei.
1013 Defined as
1015 .. math::
1017 \mathrm{bei}(x) = \Im[J_0(x e^{3 \pi i / 4})]
1019 where :math:`J_0` is the Bessel function of the first kind of
1020 order zero (see `jv`). See [dlmf]_ for more details.
1022 Parameters
1023 ----------
1024 x : array_like
1025 Real argument.
1026 out : ndarray, optional
1027 Optional output array for the function results.
1029 Returns
1030 -------
1031 scalar or ndarray
1032 Values of the Kelvin function.
1034 See Also
1035 --------
1036 ber : the corresponding real part
1037 beip : the derivative of bei
1038 jv : Bessel function of the first kind
1040 References
1041 ----------
1042 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1043 https://dlmf.nist.gov/10.61
1045 Examples
1046 --------
1047 It can be expressed using Bessel functions.
1049 >>> import numpy as np
1050 >>> import scipy.special as sc
1051 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
1052 >>> sc.jv(0, x * np.exp(3 * np.pi * 1j / 4)).imag
1053 array([0.24956604, 0.97229163, 1.93758679, 2.29269032])
1054 >>> sc.bei(x)
1055 array([0.24956604, 0.97229163, 1.93758679, 2.29269032])
1057 """)
1059add_newdoc("beip",
1060 r"""
1061 beip(x, out=None)
1063 Derivative of the Kelvin function bei.
1065 Parameters
1066 ----------
1067 x : array_like
1068 Real argument.
1069 out : ndarray, optional
1070 Optional output array for the function results.
1072 Returns
1073 -------
1074 scalar or ndarray
1075 The values of the derivative of bei.
1077 See Also
1078 --------
1079 bei
1081 References
1082 ----------
1083 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1084 https://dlmf.nist.gov/10#PT5
1086 """)
1088add_newdoc("ber",
1089 r"""
1090 ber(x, out=None)
1092 Kelvin function ber.
1094 Defined as
1096 .. math::
1098 \mathrm{ber}(x) = \Re[J_0(x e^{3 \pi i / 4})]
1100 where :math:`J_0` is the Bessel function of the first kind of
1101 order zero (see `jv`). See [dlmf]_ for more details.
1103 Parameters
1104 ----------
1105 x : array_like
1106 Real argument.
1107 out : ndarray, optional
1108 Optional output array for the function results.
1110 Returns
1111 -------
1112 scalar or ndarray
1113 Values of the Kelvin function.
1115 See Also
1116 --------
1117 bei : the corresponding real part
1118 berp : the derivative of bei
1119 jv : Bessel function of the first kind
1121 References
1122 ----------
1123 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1124 https://dlmf.nist.gov/10.61
1126 Examples
1127 --------
1128 It can be expressed using Bessel functions.
1130 >>> import numpy as np
1131 >>> import scipy.special as sc
1132 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
1133 >>> sc.jv(0, x * np.exp(3 * np.pi * 1j / 4)).real
1134 array([ 0.98438178, 0.75173418, -0.22138025, -2.56341656])
1135 >>> sc.ber(x)
1136 array([ 0.98438178, 0.75173418, -0.22138025, -2.56341656])
1138 """)
1140add_newdoc("berp",
1141 r"""
1142 berp(x, out=None)
1144 Derivative of the Kelvin function ber.
1146 Parameters
1147 ----------
1148 x : array_like
1149 Real argument.
1150 out : ndarray, optional
1151 Optional output array for the function results.
1153 Returns
1154 -------
1155 scalar or ndarray
1156 The values of the derivative of ber.
1158 See Also
1159 --------
1160 ber
1162 References
1163 ----------
1164 .. [dlmf] NIST, Digital Library of Mathematical Functions,
1165 https://dlmf.nist.gov/10#PT5
1167 """)
1169add_newdoc("besselpoly",
1170 r"""
1171 besselpoly(a, lmb, nu, out=None)
1173 Weighted integral of the Bessel function of the first kind.
1175 Computes
1177 .. math::
1179 \int_0^1 x^\lambda J_\nu(2 a x) \, dx
1181 where :math:`J_\nu` is a Bessel function and :math:`\lambda=lmb`,
1182 :math:`\nu=nu`.
1184 Parameters
1185 ----------
1186 a : array_like
1187 Scale factor inside the Bessel function.
1188 lmb : array_like
1189 Power of `x`
1190 nu : array_like
1191 Order of the Bessel function.
1192 out : ndarray, optional
1193 Optional output array for the function results.
1195 Returns
1196 -------
1197 scalar or ndarray
1198 Value of the integral.
1200 References
1201 ----------
1202 .. [1] Cephes Mathematical Functions Library,
1203 http://www.netlib.org/cephes/
1205 Examples
1206 --------
1207 Evaluate the function for one parameter set.
1209 >>> from scipy.special import besselpoly
1210 >>> besselpoly(1, 1, 1)
1211 0.24449718372863877
1213 Evaluate the function for different scale factors.
1215 >>> import numpy as np
1216 >>> factors = np.array([0., 3., 6.])
1217 >>> besselpoly(factors, 1, 1)
1218 array([ 0. , -0.00549029, 0.00140174])
1220 Plot the function for varying powers, orders and scales.
1222 >>> import matplotlib.pyplot as plt
1223 >>> fig, ax = plt.subplots()
1224 >>> powers = np.linspace(0, 10, 100)
1225 >>> orders = [1, 2, 3]
1226 >>> scales = [1, 2]
1227 >>> all_combinations = [(order, scale) for order in orders
1228 ... for scale in scales]
1229 >>> for order, scale in all_combinations:
1230 ... ax.plot(powers, besselpoly(scale, powers, order),
1231 ... label=rf"$\nu={order}, a={scale}$")
1232 >>> ax.legend()
1233 >>> ax.set_xlabel(r"$\lambda$")
1234 >>> ax.set_ylabel(r"$\int_0^1 x^{\lambda} J_{\nu}(2ax)\,dx$")
1235 >>> plt.show()
1236 """)
1238add_newdoc("beta",
1239 r"""
1240 beta(a, b, out=None)
1242 Beta function.
1244 This function is defined in [1]_ as
1246 .. math::
1248 B(a, b) = \int_0^1 t^{a-1}(1-t)^{b-1}dt
1249 = \frac{\Gamma(a)\Gamma(b)}{\Gamma(a+b)},
1251 where :math:`\Gamma` is the gamma function.
1253 Parameters
1254 ----------
1255 a, b : array_like
1256 Real-valued arguments
1257 out : ndarray, optional
1258 Optional output array for the function result
1260 Returns
1261 -------
1262 scalar or ndarray
1263 Value of the beta function
1265 See Also
1266 --------
1267 gamma : the gamma function
1268 betainc : the regularized incomplete beta function
1269 betaln : the natural logarithm of the absolute
1270 value of the beta function
1272 References
1273 ----------
1274 .. [1] NIST Digital Library of Mathematical Functions,
1275 Eq. 5.12.1. https://dlmf.nist.gov/5.12
1277 Examples
1278 --------
1279 >>> import scipy.special as sc
1281 The beta function relates to the gamma function by the
1282 definition given above:
1284 >>> sc.beta(2, 3)
1285 0.08333333333333333
1286 >>> sc.gamma(2)*sc.gamma(3)/sc.gamma(2 + 3)
1287 0.08333333333333333
1289 As this relationship demonstrates, the beta function
1290 is symmetric:
1292 >>> sc.beta(1.7, 2.4)
1293 0.16567527689031739
1294 >>> sc.beta(2.4, 1.7)
1295 0.16567527689031739
1297 This function satisfies :math:`B(1, b) = 1/b`:
1299 >>> sc.beta(1, 4)
1300 0.25
1302 """)
1304add_newdoc("betainc",
1305 r"""
1306 betainc(a, b, x, out=None)
1308 Regularized incomplete beta function.
1310 Computes the regularized incomplete beta function, defined as [1]_:
1312 .. math::
1314 I_x(a, b) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)} \int_0^x
1315 t^{a-1}(1-t)^{b-1}dt,
1317 for :math:`0 \leq x \leq 1`.
1319 Parameters
1320 ----------
1321 a, b : array_like
1322 Positive, real-valued parameters
1323 x : array_like
1324 Real-valued such that :math:`0 \leq x \leq 1`,
1325 the upper limit of integration
1326 out : ndarray, optional
1327 Optional output array for the function values
1329 Returns
1330 -------
1331 scalar or ndarray
1332 Value of the regularized incomplete beta function
1334 See Also
1335 --------
1336 beta : beta function
1337 betaincinv : inverse of the regularized incomplete beta function
1339 Notes
1340 -----
1341 The term *regularized* in the name of this function refers to the
1342 scaling of the function by the gamma function terms shown in the
1343 formula. When not qualified as *regularized*, the name *incomplete
1344 beta function* often refers to just the integral expression,
1345 without the gamma terms. One can use the function `beta` from
1346 `scipy.special` to get this "nonregularized" incomplete beta
1347 function by multiplying the result of ``betainc(a, b, x)`` by
1348 ``beta(a, b)``.
1350 References
1351 ----------
1352 .. [1] NIST Digital Library of Mathematical Functions
1353 https://dlmf.nist.gov/8.17
1355 Examples
1356 --------
1358 Let :math:`B(a, b)` be the `beta` function.
1360 >>> import scipy.special as sc
1362 The coefficient in terms of `gamma` is equal to
1363 :math:`1/B(a, b)`. Also, when :math:`x=1`
1364 the integral is equal to :math:`B(a, b)`.
1365 Therefore, :math:`I_{x=1}(a, b) = 1` for any :math:`a, b`.
1367 >>> sc.betainc(0.2, 3.5, 1.0)
1368 1.0
1370 It satisfies
1371 :math:`I_x(a, b) = x^a F(a, 1-b, a+1, x)/ (aB(a, b))`,
1372 where :math:`F` is the hypergeometric function `hyp2f1`:
1374 >>> a, b, x = 1.4, 3.1, 0.5
1375 >>> x**a * sc.hyp2f1(a, 1 - b, a + 1, x)/(a * sc.beta(a, b))
1376 0.8148904036225295
1377 >>> sc.betainc(a, b, x)
1378 0.8148904036225296
1380 This functions satisfies the relationship
1381 :math:`I_x(a, b) = 1 - I_{1-x}(b, a)`:
1383 >>> sc.betainc(2.2, 3.1, 0.4)
1384 0.49339638807619446
1385 >>> 1 - sc.betainc(3.1, 2.2, 1 - 0.4)
1386 0.49339638807619446
1388 """)
1390add_newdoc("betaincinv",
1391 r"""
1392 betaincinv(a, b, y, out=None)
1394 Inverse of the regularized incomplete beta function.
1396 Computes :math:`x` such that:
1398 .. math::
1400 y = I_x(a, b) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)}
1401 \int_0^x t^{a-1}(1-t)^{b-1}dt,
1403 where :math:`I_x` is the normalized incomplete beta
1404 function `betainc` and
1405 :math:`\Gamma` is the `gamma` function [1]_.
1407 Parameters
1408 ----------
1409 a, b : array_like
1410 Positive, real-valued parameters
1411 y : array_like
1412 Real-valued input
1413 out : ndarray, optional
1414 Optional output array for function values
1416 Returns
1417 -------
1418 scalar or ndarray
1419 Value of the inverse of the regularized incomplete beta function
1421 See Also
1422 --------
1423 betainc : regularized incomplete beta function
1424 gamma : gamma function
1426 References
1427 ----------
1428 .. [1] NIST Digital Library of Mathematical Functions
1429 https://dlmf.nist.gov/8.17
1431 Examples
1432 --------
1433 >>> import scipy.special as sc
1435 This function is the inverse of `betainc` for fixed
1436 values of :math:`a` and :math:`b`.
1438 >>> a, b = 1.2, 3.1
1439 >>> y = sc.betainc(a, b, 0.2)
1440 >>> sc.betaincinv(a, b, y)
1441 0.2
1442 >>>
1443 >>> a, b = 7.5, 0.4
1444 >>> x = sc.betaincinv(a, b, 0.5)
1445 >>> sc.betainc(a, b, x)
1446 0.5
1448 """)
1450add_newdoc("betaln",
1451 """
1452 betaln(a, b, out=None)
1454 Natural logarithm of absolute value of beta function.
1456 Computes ``ln(abs(beta(a, b)))``.
1458 Parameters
1459 ----------
1460 a, b : array_like
1461 Positive, real-valued parameters
1462 out : ndarray, optional
1463 Optional output array for function values
1465 Returns
1466 -------
1467 scalar or ndarray
1468 Value of the betaln function
1470 See Also
1471 --------
1472 gamma : the gamma function
1473 betainc : the regularized incomplete beta function
1474 beta : the beta function
1476 Examples
1477 --------
1478 >>> import numpy as np
1479 >>> from scipy.special import betaln, beta
1481 Verify that, for moderate values of ``a`` and ``b``, ``betaln(a, b)``
1482 is the same as ``log(beta(a, b))``:
1484 >>> betaln(3, 4)
1485 -4.0943445622221
1487 >>> np.log(beta(3, 4))
1488 -4.0943445622221
1490 In the following ``beta(a, b)`` underflows to 0, so we can't compute
1491 the logarithm of the actual value.
1493 >>> a = 400
1494 >>> b = 900
1495 >>> beta(a, b)
1496 0.0
1498 We can compute the logarithm of ``beta(a, b)`` by using `betaln`:
1500 >>> betaln(a, b)
1501 -804.3069951764146
1503 """)
1505add_newdoc("boxcox",
1506 """
1507 boxcox(x, lmbda, out=None)
1509 Compute the Box-Cox transformation.
1511 The Box-Cox transformation is::
1513 y = (x**lmbda - 1) / lmbda if lmbda != 0
1514 log(x) if lmbda == 0
1516 Returns `nan` if ``x < 0``.
1517 Returns `-inf` if ``x == 0`` and ``lmbda < 0``.
1519 Parameters
1520 ----------
1521 x : array_like
1522 Data to be transformed.
1523 lmbda : array_like
1524 Power parameter of the Box-Cox transform.
1525 out : ndarray, optional
1526 Optional output array for the function values
1528 Returns
1529 -------
1530 y : scalar or ndarray
1531 Transformed data.
1533 Notes
1534 -----
1536 .. versionadded:: 0.14.0
1538 Examples
1539 --------
1540 >>> from scipy.special import boxcox
1541 >>> boxcox([1, 4, 10], 2.5)
1542 array([ 0. , 12.4 , 126.09110641])
1543 >>> boxcox(2, [0, 1, 2])
1544 array([ 0.69314718, 1. , 1.5 ])
1545 """)
1547add_newdoc("boxcox1p",
1548 """
1549 boxcox1p(x, lmbda, out=None)
1551 Compute the Box-Cox transformation of 1 + `x`.
1553 The Box-Cox transformation computed by `boxcox1p` is::
1555 y = ((1+x)**lmbda - 1) / lmbda if lmbda != 0
1556 log(1+x) if lmbda == 0
1558 Returns `nan` if ``x < -1``.
1559 Returns `-inf` if ``x == -1`` and ``lmbda < 0``.
1561 Parameters
1562 ----------
1563 x : array_like
1564 Data to be transformed.
1565 lmbda : array_like
1566 Power parameter of the Box-Cox transform.
1567 out : ndarray, optional
1568 Optional output array for the function values
1570 Returns
1571 -------
1572 y : scalar or ndarray
1573 Transformed data.
1575 Notes
1576 -----
1578 .. versionadded:: 0.14.0
1580 Examples
1581 --------
1582 >>> from scipy.special import boxcox1p
1583 >>> boxcox1p(1e-4, [0, 0.5, 1])
1584 array([ 9.99950003e-05, 9.99975001e-05, 1.00000000e-04])
1585 >>> boxcox1p([0.01, 0.1], 0.25)
1586 array([ 0.00996272, 0.09645476])
1587 """)
1589add_newdoc("inv_boxcox",
1590 """
1591 inv_boxcox(y, lmbda, out=None)
1593 Compute the inverse of the Box-Cox transformation.
1595 Find ``x`` such that::
1597 y = (x**lmbda - 1) / lmbda if lmbda != 0
1598 log(x) if lmbda == 0
1600 Parameters
1601 ----------
1602 y : array_like
1603 Data to be transformed.
1604 lmbda : array_like
1605 Power parameter of the Box-Cox transform.
1606 out : ndarray, optional
1607 Optional output array for the function values
1609 Returns
1610 -------
1611 x : scalar or ndarray
1612 Transformed data.
1614 Notes
1615 -----
1617 .. versionadded:: 0.16.0
1619 Examples
1620 --------
1621 >>> from scipy.special import boxcox, inv_boxcox
1622 >>> y = boxcox([1, 4, 10], 2.5)
1623 >>> inv_boxcox(y, 2.5)
1624 array([1., 4., 10.])
1625 """)
1627add_newdoc("inv_boxcox1p",
1628 """
1629 inv_boxcox1p(y, lmbda, out=None)
1631 Compute the inverse of the Box-Cox transformation.
1633 Find ``x`` such that::
1635 y = ((1+x)**lmbda - 1) / lmbda if lmbda != 0
1636 log(1+x) if lmbda == 0
1638 Parameters
1639 ----------
1640 y : array_like
1641 Data to be transformed.
1642 lmbda : array_like
1643 Power parameter of the Box-Cox transform.
1644 out : ndarray, optional
1645 Optional output array for the function values
1647 Returns
1648 -------
1649 x : scalar or ndarray
1650 Transformed data.
1652 Notes
1653 -----
1655 .. versionadded:: 0.16.0
1657 Examples
1658 --------
1659 >>> from scipy.special import boxcox1p, inv_boxcox1p
1660 >>> y = boxcox1p([1, 4, 10], 2.5)
1661 >>> inv_boxcox1p(y, 2.5)
1662 array([1., 4., 10.])
1663 """)
1665add_newdoc("btdtr",
1666 r"""
1667 btdtr(a, b, x, out=None)
1669 Cumulative distribution function of the beta distribution.
1671 Returns the integral from zero to `x` of the beta probability density
1672 function,
1674 .. math::
1675 I = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
1677 where :math:`\Gamma` is the gamma function.
1679 Parameters
1680 ----------
1681 a : array_like
1682 Shape parameter (a > 0).
1683 b : array_like
1684 Shape parameter (b > 0).
1685 x : array_like
1686 Upper limit of integration, in [0, 1].
1687 out : ndarray, optional
1688 Optional output array for the function values
1690 Returns
1691 -------
1692 I : scalar or ndarray
1693 Cumulative distribution function of the beta distribution with
1694 parameters `a` and `b` at `x`.
1696 See Also
1697 --------
1698 betainc
1700 Notes
1701 -----
1702 This function is identical to the incomplete beta integral function
1703 `betainc`.
1705 Wrapper for the Cephes [1]_ routine `btdtr`.
1707 References
1708 ----------
1709 .. [1] Cephes Mathematical Functions Library,
1710 http://www.netlib.org/cephes/
1712 """)
1714add_newdoc("btdtri",
1715 r"""
1716 btdtri(a, b, p, out=None)
1718 The `p`-th quantile of the beta distribution.
1720 This function is the inverse of the beta cumulative distribution function,
1721 `btdtr`, returning the value of `x` for which `btdtr(a, b, x) = p`, or
1723 .. math::
1724 p = \int_0^x \frac{\Gamma(a + b)}{\Gamma(a)\Gamma(b)} t^{a-1} (1-t)^{b-1}\,dt
1726 Parameters
1727 ----------
1728 a : array_like
1729 Shape parameter (`a` > 0).
1730 b : array_like
1731 Shape parameter (`b` > 0).
1732 p : array_like
1733 Cumulative probability, in [0, 1].
1734 out : ndarray, optional
1735 Optional output array for the function values
1737 Returns
1738 -------
1739 x : scalar or ndarray
1740 The quantile corresponding to `p`.
1742 See Also
1743 --------
1744 betaincinv
1745 btdtr
1747 Notes
1748 -----
1749 The value of `x` is found by interval halving or Newton iterations.
1751 Wrapper for the Cephes [1]_ routine `incbi`, which solves the equivalent
1752 problem of finding the inverse of the incomplete beta integral.
1754 References
1755 ----------
1756 .. [1] Cephes Mathematical Functions Library,
1757 http://www.netlib.org/cephes/
1759 """)
1761add_newdoc("cbrt",
1762 """
1763 cbrt(x, out=None)
1765 Element-wise cube root of `x`.
1767 Parameters
1768 ----------
1769 x : array_like
1770 `x` must contain real numbers.
1771 out : ndarray, optional
1772 Optional output array for the function values
1774 Returns
1775 -------
1776 scalar or ndarray
1777 The cube root of each value in `x`.
1779 Examples
1780 --------
1781 >>> from scipy.special import cbrt
1783 >>> cbrt(8)
1784 2.0
1785 >>> cbrt([-8, -3, 0.125, 1.331])
1786 array([-2. , -1.44224957, 0.5 , 1.1 ])
1788 """)
1790add_newdoc("chdtr",
1791 r"""
1792 chdtr(v, x, out=None)
1794 Chi square cumulative distribution function.
1796 Returns the area under the left tail (from 0 to `x`) of the Chi
1797 square probability density function with `v` degrees of freedom:
1799 .. math::
1801 \frac{1}{2^{v/2} \Gamma(v/2)} \int_0^x t^{v/2 - 1} e^{-t/2} dt
1803 Here :math:`\Gamma` is the Gamma function; see `gamma`. This
1804 integral can be expressed in terms of the regularized lower
1805 incomplete gamma function `gammainc` as
1806 ``gammainc(v / 2, x / 2)``. [1]_
1808 Parameters
1809 ----------
1810 v : array_like
1811 Degrees of freedom.
1812 x : array_like
1813 Upper bound of the integral.
1814 out : ndarray, optional
1815 Optional output array for the function results.
1817 Returns
1818 -------
1819 scalar or ndarray
1820 Values of the cumulative distribution function.
1822 See Also
1823 --------
1824 chdtrc, chdtri, chdtriv, gammainc
1826 References
1827 ----------
1828 .. [1] Chi-Square distribution,
1829 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1831 Examples
1832 --------
1833 >>> import numpy as np
1834 >>> import scipy.special as sc
1836 It can be expressed in terms of the regularized lower incomplete
1837 gamma function.
1839 >>> v = 1
1840 >>> x = np.arange(4)
1841 >>> sc.chdtr(v, x)
1842 array([0. , 0.68268949, 0.84270079, 0.91673548])
1843 >>> sc.gammainc(v / 2, x / 2)
1844 array([0. , 0.68268949, 0.84270079, 0.91673548])
1846 """)
1848add_newdoc("chdtrc",
1849 r"""
1850 chdtrc(v, x, out=None)
1852 Chi square survival function.
1854 Returns the area under the right hand tail (from `x` to infinity)
1855 of the Chi square probability density function with `v` degrees of
1856 freedom:
1858 .. math::
1860 \frac{1}{2^{v/2} \Gamma(v/2)} \int_x^\infty t^{v/2 - 1} e^{-t/2} dt
1862 Here :math:`\Gamma` is the Gamma function; see `gamma`. This
1863 integral can be expressed in terms of the regularized upper
1864 incomplete gamma function `gammaincc` as
1865 ``gammaincc(v / 2, x / 2)``. [1]_
1867 Parameters
1868 ----------
1869 v : array_like
1870 Degrees of freedom.
1871 x : array_like
1872 Lower bound of the integral.
1873 out : ndarray, optional
1874 Optional output array for the function results.
1876 Returns
1877 -------
1878 scalar or ndarray
1879 Values of the survival function.
1881 See Also
1882 --------
1883 chdtr, chdtri, chdtriv, gammaincc
1885 References
1886 ----------
1887 .. [1] Chi-Square distribution,
1888 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1890 Examples
1891 --------
1892 >>> import numpy as np
1893 >>> import scipy.special as sc
1895 It can be expressed in terms of the regularized upper incomplete
1896 gamma function.
1898 >>> v = 1
1899 >>> x = np.arange(4)
1900 >>> sc.chdtrc(v, x)
1901 array([1. , 0.31731051, 0.15729921, 0.08326452])
1902 >>> sc.gammaincc(v / 2, x / 2)
1903 array([1. , 0.31731051, 0.15729921, 0.08326452])
1905 """)
1907add_newdoc("chdtri",
1908 """
1909 chdtri(v, p, out=None)
1911 Inverse to `chdtrc` with respect to `x`.
1913 Returns `x` such that ``chdtrc(v, x) == p``.
1915 Parameters
1916 ----------
1917 v : array_like
1918 Degrees of freedom.
1919 p : array_like
1920 Probability.
1921 out : ndarray, optional
1922 Optional output array for the function results.
1924 Returns
1925 -------
1926 x : scalar or ndarray
1927 Value so that the probability a Chi square random variable
1928 with `v` degrees of freedom is greater than `x` equals `p`.
1930 See Also
1931 --------
1932 chdtrc, chdtr, chdtriv
1934 References
1935 ----------
1936 .. [1] Chi-Square distribution,
1937 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1939 Examples
1940 --------
1941 >>> import scipy.special as sc
1943 It inverts `chdtrc`.
1945 >>> v, p = 1, 0.3
1946 >>> sc.chdtrc(v, sc.chdtri(v, p))
1947 0.3
1948 >>> x = 1
1949 >>> sc.chdtri(v, sc.chdtrc(v, x))
1950 1.0
1952 """)
1954add_newdoc("chdtriv",
1955 """
1956 chdtriv(p, x, out=None)
1958 Inverse to `chdtr` with respect to `v`.
1960 Returns `v` such that ``chdtr(v, x) == p``.
1962 Parameters
1963 ----------
1964 p : array_like
1965 Probability that the Chi square random variable is less than
1966 or equal to `x`.
1967 x : array_like
1968 Nonnegative input.
1969 out : ndarray, optional
1970 Optional output array for the function results.
1972 Returns
1973 -------
1974 scalar or ndarray
1975 Degrees of freedom.
1977 See Also
1978 --------
1979 chdtr, chdtrc, chdtri
1981 References
1982 ----------
1983 .. [1] Chi-Square distribution,
1984 https://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm
1986 Examples
1987 --------
1988 >>> import scipy.special as sc
1990 It inverts `chdtr`.
1992 >>> p, x = 0.5, 1
1993 >>> sc.chdtr(sc.chdtriv(p, x), x)
1994 0.5000000000202172
1995 >>> v = 1
1996 >>> sc.chdtriv(sc.chdtr(v, x), v)
1997 1.0000000000000013
1999 """)
2001add_newdoc("chndtr",
2002 r"""
2003 chndtr(x, df, nc, out=None)
2005 Non-central chi square cumulative distribution function
2007 The cumulative distribution function is given by:
2009 .. math::
2011 P(\chi^{\prime 2} \vert \nu, \lambda) =\sum_{j=0}^{\infty}
2012 e^{-\lambda /2}
2013 \frac{(\lambda /2)^j}{j!} P(\chi^{\prime 2} \vert \nu + 2j),
2015 where :math:`\nu > 0` is the degrees of freedom (``df``) and
2016 :math:`\lambda \geq 0` is the non-centrality parameter (``nc``).
2018 Parameters
2019 ----------
2020 x : array_like
2021 Upper bound of the integral; must satisfy ``x >= 0``
2022 df : array_like
2023 Degrees of freedom; must satisfy ``df > 0``
2024 nc : array_like
2025 Non-centrality parameter; must satisfy ``nc >= 0``
2026 out : ndarray, optional
2027 Optional output array for the function results
2029 Returns
2030 -------
2031 x : scalar or ndarray
2032 Value of the non-central chi square cumulative distribution function.
2034 See Also
2035 --------
2036 chndtrix, chndtridf, chndtrinc
2038 """)
2040add_newdoc("chndtrix",
2041 """
2042 chndtrix(p, df, nc, out=None)
2044 Inverse to `chndtr` vs `x`
2046 Calculated using a search to find a value for `x` that produces the
2047 desired value of `p`.
2049 Parameters
2050 ----------
2051 p : array_like
2052 Probability; must satisfy ``0 <= p < 1``
2053 df : array_like
2054 Degrees of freedom; must satisfy ``df > 0``
2055 nc : array_like
2056 Non-centrality parameter; must satisfy ``nc >= 0``
2057 out : ndarray, optional
2058 Optional output array for the function results
2060 Returns
2061 -------
2062 x : scalar or ndarray
2063 Value so that the probability a non-central Chi square random variable
2064 with `df` degrees of freedom and non-centrality, `nc`, is greater than
2065 `x` equals `p`.
2067 See Also
2068 --------
2069 chndtr, chndtridf, chndtrinc
2071 """)
2073add_newdoc("chndtridf",
2074 """
2075 chndtridf(x, p, nc, out=None)
2077 Inverse to `chndtr` vs `df`
2079 Calculated using a search to find a value for `df` that produces the
2080 desired value of `p`.
2082 Parameters
2083 ----------
2084 x : array_like
2085 Upper bound of the integral; must satisfy ``x >= 0``
2086 p : array_like
2087 Probability; must satisfy ``0 <= p < 1``
2088 nc : array_like
2089 Non-centrality parameter; must satisfy ``nc >= 0``
2090 out : ndarray, optional
2091 Optional output array for the function results
2093 Returns
2094 -------
2095 df : scalar or ndarray
2096 Degrees of freedom
2098 See Also
2099 --------
2100 chndtr, chndtrix, chndtrinc
2102 """)
2104add_newdoc("chndtrinc",
2105 """
2106 chndtrinc(x, df, p, out=None)
2108 Inverse to `chndtr` vs `nc`
2110 Calculated using a search to find a value for `df` that produces the
2111 desired value of `p`.
2113 Parameters
2114 ----------
2115 x : array_like
2116 Upper bound of the integral; must satisfy ``x >= 0``
2117 df : array_like
2118 Degrees of freedom; must satisfy ``df > 0``
2119 p : array_like
2120 Probability; must satisfy ``0 <= p < 1``
2121 out : ndarray, optional
2122 Optional output array for the function results
2124 Returns
2125 -------
2126 nc : scalar or ndarray
2127 Non-centrality
2129 See Also
2130 --------
2131 chndtr, chndtrix, chndtrinc
2133 """)
2135add_newdoc("cosdg",
2136 """
2137 cosdg(x, out=None)
2139 Cosine of the angle `x` given in degrees.
2141 Parameters
2142 ----------
2143 x : array_like
2144 Angle, given in degrees.
2145 out : ndarray, optional
2146 Optional output array for the function results.
2148 Returns
2149 -------
2150 scalar or ndarray
2151 Cosine of the input.
2153 See Also
2154 --------
2155 sindg, tandg, cotdg
2157 Examples
2158 --------
2159 >>> import numpy as np
2160 >>> import scipy.special as sc
2162 It is more accurate than using cosine directly.
2164 >>> x = 90 + 180 * np.arange(3)
2165 >>> sc.cosdg(x)
2166 array([-0., 0., -0.])
2167 >>> np.cos(x * np.pi / 180)
2168 array([ 6.1232340e-17, -1.8369702e-16, 3.0616170e-16])
2170 """)
2172add_newdoc("cosm1",
2173 """
2174 cosm1(x, out=None)
2176 cos(x) - 1 for use when `x` is near zero.
2178 Parameters
2179 ----------
2180 x : array_like
2181 Real valued argument.
2182 out : ndarray, optional
2183 Optional output array for the function results.
2185 Returns
2186 -------
2187 scalar or ndarray
2188 Values of ``cos(x) - 1``.
2190 See Also
2191 --------
2192 expm1, log1p
2194 Examples
2195 --------
2196 >>> import numpy as np
2197 >>> import scipy.special as sc
2199 It is more accurate than computing ``cos(x) - 1`` directly for
2200 ``x`` around 0.
2202 >>> x = 1e-30
2203 >>> np.cos(x) - 1
2204 0.0
2205 >>> sc.cosm1(x)
2206 -5.0000000000000005e-61
2208 """)
2210add_newdoc("cotdg",
2211 """
2212 cotdg(x, out=None)
2214 Cotangent of the angle `x` given in degrees.
2216 Parameters
2217 ----------
2218 x : array_like
2219 Angle, given in degrees.
2220 out : ndarray, optional
2221 Optional output array for the function results.
2223 Returns
2224 -------
2225 scalar or ndarray
2226 Cotangent at the input.
2228 See Also
2229 --------
2230 sindg, cosdg, tandg
2232 Examples
2233 --------
2234 >>> import numpy as np
2235 >>> import scipy.special as sc
2237 It is more accurate than using cotangent directly.
2239 >>> x = 90 + 180 * np.arange(3)
2240 >>> sc.cotdg(x)
2241 array([0., 0., 0.])
2242 >>> 1 / np.tan(x * np.pi / 180)
2243 array([6.1232340e-17, 1.8369702e-16, 3.0616170e-16])
2245 """)
2247add_newdoc("dawsn",
2248 """
2249 dawsn(x, out=None)
2251 Dawson's integral.
2253 Computes::
2255 exp(-x**2) * integral(exp(t**2), t=0..x).
2257 Parameters
2258 ----------
2259 x : array_like
2260 Function parameter.
2261 out : ndarray, optional
2262 Optional output array for the function values
2264 Returns
2265 -------
2266 y : scalar or ndarray
2267 Value of the integral.
2269 See Also
2270 --------
2271 wofz, erf, erfc, erfcx, erfi
2273 References
2274 ----------
2275 .. [1] Steven G. Johnson, Faddeeva W function implementation.
2276 http://ab-initio.mit.edu/Faddeeva
2278 Examples
2279 --------
2280 >>> import numpy as np
2281 >>> from scipy import special
2282 >>> import matplotlib.pyplot as plt
2283 >>> x = np.linspace(-15, 15, num=1000)
2284 >>> plt.plot(x, special.dawsn(x))
2285 >>> plt.xlabel('$x$')
2286 >>> plt.ylabel('$dawsn(x)$')
2287 >>> plt.show()
2289 """)
2291add_newdoc("ellipe",
2292 r"""
2293 ellipe(m, out=None)
2295 Complete elliptic integral of the second kind
2297 This function is defined as
2299 .. math:: E(m) = \int_0^{\pi/2} [1 - m \sin(t)^2]^{1/2} dt
2301 Parameters
2302 ----------
2303 m : array_like
2304 Defines the parameter of the elliptic integral.
2305 out : ndarray, optional
2306 Optional output array for the function values
2308 Returns
2309 -------
2310 E : scalar or ndarray
2311 Value of the elliptic integral.
2313 Notes
2314 -----
2315 Wrapper for the Cephes [1]_ routine `ellpe`.
2317 For `m > 0` the computation uses the approximation,
2319 .. math:: E(m) \approx P(1-m) - (1-m) \log(1-m) Q(1-m),
2321 where :math:`P` and :math:`Q` are tenth-order polynomials. For
2322 `m < 0`, the relation
2324 .. math:: E(m) = E(m/(m - 1)) \sqrt(1-m)
2326 is used.
2328 The parameterization in terms of :math:`m` follows that of section
2329 17.2 in [2]_. Other parameterizations in terms of the
2330 complementary parameter :math:`1 - m`, modular angle
2331 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2332 used, so be careful that you choose the correct parameter.
2334 The Legendre E integral is related to Carlson's symmetric R_D or R_G
2335 functions in multiple ways [3]_. For example,
2337 .. math:: E(m) = 2 R_G(0, 1-k^2, 1) .
2339 See Also
2340 --------
2341 ellipkm1 : Complete elliptic integral of the first kind, near `m` = 1
2342 ellipk : Complete elliptic integral of the first kind
2343 ellipkinc : Incomplete elliptic integral of the first kind
2344 ellipeinc : Incomplete elliptic integral of the second kind
2345 elliprd : Symmetric elliptic integral of the second kind.
2346 elliprg : Completely-symmetric elliptic integral of the second kind.
2348 References
2349 ----------
2350 .. [1] Cephes Mathematical Functions Library,
2351 http://www.netlib.org/cephes/
2352 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
2353 Handbook of Mathematical Functions with Formulas,
2354 Graphs, and Mathematical Tables. New York: Dover, 1972.
2355 .. [3] NIST Digital Library of Mathematical
2356 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2357 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2359 Examples
2360 --------
2361 This function is used in finding the circumference of an
2362 ellipse with semi-major axis `a` and semi-minor axis `b`.
2364 >>> import numpy as np
2365 >>> from scipy import special
2367 >>> a = 3.5
2368 >>> b = 2.1
2369 >>> e_sq = 1.0 - b**2/a**2 # eccentricity squared
2371 Then the circumference is found using the following:
2373 >>> C = 4*a*special.ellipe(e_sq) # circumference formula
2374 >>> C
2375 17.868899204378693
2377 When `a` and `b` are the same (meaning eccentricity is 0),
2378 this reduces to the circumference of a circle.
2380 >>> 4*a*special.ellipe(0.0) # formula for ellipse with a = b
2381 21.991148575128552
2382 >>> 2*np.pi*a # formula for circle of radius a
2383 21.991148575128552
2385 """)
2387add_newdoc("ellipeinc",
2388 r"""
2389 ellipeinc(phi, m, out=None)
2391 Incomplete elliptic integral of the second kind
2393 This function is defined as
2395 .. math:: E(\phi, m) = \int_0^{\phi} [1 - m \sin(t)^2]^{1/2} dt
2397 Parameters
2398 ----------
2399 phi : array_like
2400 amplitude of the elliptic integral.
2401 m : array_like
2402 parameter of the elliptic integral.
2403 out : ndarray, optional
2404 Optional output array for the function values
2406 Returns
2407 -------
2408 E : scalar or ndarray
2409 Value of the elliptic integral.
2411 Notes
2412 -----
2413 Wrapper for the Cephes [1]_ routine `ellie`.
2415 Computation uses arithmetic-geometric means algorithm.
2417 The parameterization in terms of :math:`m` follows that of section
2418 17.2 in [2]_. Other parameterizations in terms of the
2419 complementary parameter :math:`1 - m`, modular angle
2420 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2421 used, so be careful that you choose the correct parameter.
2423 The Legendre E incomplete integral can be related to combinations
2424 of Carlson's symmetric integrals R_D, R_F, and R_G in multiple
2425 ways [3]_. For example, with :math:`c = \csc^2\phi`,
2427 .. math::
2428 E(\phi, m) = R_F(c-1, c-k^2, c)
2429 - \frac{1}{3} k^2 R_D(c-1, c-k^2, c) .
2431 See Also
2432 --------
2433 ellipkm1 : Complete elliptic integral of the first kind, near `m` = 1
2434 ellipk : Complete elliptic integral of the first kind
2435 ellipkinc : Incomplete elliptic integral of the first kind
2436 ellipe : Complete elliptic integral of the second kind
2437 elliprd : Symmetric elliptic integral of the second kind.
2438 elliprf : Completely-symmetric elliptic integral of the first kind.
2439 elliprg : Completely-symmetric elliptic integral of the second kind.
2441 References
2442 ----------
2443 .. [1] Cephes Mathematical Functions Library,
2444 http://www.netlib.org/cephes/
2445 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
2446 Handbook of Mathematical Functions with Formulas,
2447 Graphs, and Mathematical Tables. New York: Dover, 1972.
2448 .. [3] NIST Digital Library of Mathematical
2449 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2450 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2451 """)
2453add_newdoc("ellipj",
2454 """
2455 ellipj(u, m, out=None)
2457 Jacobian elliptic functions
2459 Calculates the Jacobian elliptic functions of parameter `m` between
2460 0 and 1, and real argument `u`.
2462 Parameters
2463 ----------
2464 m : array_like
2465 Parameter.
2466 u : array_like
2467 Argument.
2468 out : tuple of ndarray, optional
2469 Optional output arrays for the function values
2471 Returns
2472 -------
2473 sn, cn, dn, ph : 4-tuple of scalar or ndarray
2474 The returned functions::
2476 sn(u|m), cn(u|m), dn(u|m)
2478 The value `ph` is such that if `u = ellipkinc(ph, m)`,
2479 then `sn(u|m) = sin(ph)` and `cn(u|m) = cos(ph)`.
2481 Notes
2482 -----
2483 Wrapper for the Cephes [1]_ routine `ellpj`.
2485 These functions are periodic, with quarter-period on the real axis
2486 equal to the complete elliptic integral `ellipk(m)`.
2488 Relation to incomplete elliptic integral: If `u = ellipkinc(phi,m)`, then
2489 `sn(u|m) = sin(phi)`, and `cn(u|m) = cos(phi)`. The `phi` is called
2490 the amplitude of `u`.
2492 Computation is by means of the arithmetic-geometric mean algorithm,
2493 except when `m` is within 1e-9 of 0 or 1. In the latter case with `m`
2494 close to 1, the approximation applies only for `phi < pi/2`.
2496 See also
2497 --------
2498 ellipk : Complete elliptic integral of the first kind
2499 ellipkinc : Incomplete elliptic integral of the first kind
2501 References
2502 ----------
2503 .. [1] Cephes Mathematical Functions Library,
2504 http://www.netlib.org/cephes/
2505 """)
2507add_newdoc("ellipkm1",
2508 """
2509 ellipkm1(p, out=None)
2511 Complete elliptic integral of the first kind around `m` = 1
2513 This function is defined as
2515 .. math:: K(p) = \\int_0^{\\pi/2} [1 - m \\sin(t)^2]^{-1/2} dt
2517 where `m = 1 - p`.
2519 Parameters
2520 ----------
2521 p : array_like
2522 Defines the parameter of the elliptic integral as `m = 1 - p`.
2523 out : ndarray, optional
2524 Optional output array for the function values
2526 Returns
2527 -------
2528 K : scalar or ndarray
2529 Value of the elliptic integral.
2531 Notes
2532 -----
2533 Wrapper for the Cephes [1]_ routine `ellpk`.
2535 For `p <= 1`, computation uses the approximation,
2537 .. math:: K(p) \\approx P(p) - \\log(p) Q(p),
2539 where :math:`P` and :math:`Q` are tenth-order polynomials. The
2540 argument `p` is used internally rather than `m` so that the logarithmic
2541 singularity at `m = 1` will be shifted to the origin; this preserves
2542 maximum accuracy. For `p > 1`, the identity
2544 .. math:: K(p) = K(1/p)/\\sqrt(p)
2546 is used.
2548 See Also
2549 --------
2550 ellipk : Complete elliptic integral of the first kind
2551 ellipkinc : Incomplete elliptic integral of the first kind
2552 ellipe : Complete elliptic integral of the second kind
2553 ellipeinc : Incomplete elliptic integral of the second kind
2554 elliprf : Completely-symmetric elliptic integral of the first kind.
2556 References
2557 ----------
2558 .. [1] Cephes Mathematical Functions Library,
2559 http://www.netlib.org/cephes/
2560 """)
2562add_newdoc("ellipk",
2563 r"""
2564 ellipk(m, out=None)
2566 Complete elliptic integral of the first kind.
2568 This function is defined as
2570 .. math:: K(m) = \int_0^{\pi/2} [1 - m \sin(t)^2]^{-1/2} dt
2572 Parameters
2573 ----------
2574 m : array_like
2575 The parameter of the elliptic integral.
2576 out : ndarray, optional
2577 Optional output array for the function values
2579 Returns
2580 -------
2581 K : scalar or ndarray
2582 Value of the elliptic integral.
2584 Notes
2585 -----
2586 For more precision around point m = 1, use `ellipkm1`, which this
2587 function calls.
2589 The parameterization in terms of :math:`m` follows that of section
2590 17.2 in [1]_. Other parameterizations in terms of the
2591 complementary parameter :math:`1 - m`, modular angle
2592 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2593 used, so be careful that you choose the correct parameter.
2595 The Legendre K integral is related to Carlson's symmetric R_F
2596 function by [2]_:
2598 .. math:: K(m) = R_F(0, 1-k^2, 1) .
2600 See Also
2601 --------
2602 ellipkm1 : Complete elliptic integral of the first kind around m = 1
2603 ellipkinc : Incomplete elliptic integral of the first kind
2604 ellipe : Complete elliptic integral of the second kind
2605 ellipeinc : Incomplete elliptic integral of the second kind
2606 elliprf : Completely-symmetric elliptic integral of the first kind.
2608 References
2609 ----------
2610 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
2611 Handbook of Mathematical Functions with Formulas,
2612 Graphs, and Mathematical Tables. New York: Dover, 1972.
2613 .. [2] NIST Digital Library of Mathematical
2614 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2615 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2617 """)
2619add_newdoc("ellipkinc",
2620 r"""
2621 ellipkinc(phi, m, out=None)
2623 Incomplete elliptic integral of the first kind
2625 This function is defined as
2627 .. math:: K(\phi, m) = \int_0^{\phi} [1 - m \sin(t)^2]^{-1/2} dt
2629 This function is also called :math:`F(\phi, m)`.
2631 Parameters
2632 ----------
2633 phi : array_like
2634 amplitude of the elliptic integral
2635 m : array_like
2636 parameter of the elliptic integral
2637 out : ndarray, optional
2638 Optional output array for the function values
2640 Returns
2641 -------
2642 K : scalar or ndarray
2643 Value of the elliptic integral
2645 Notes
2646 -----
2647 Wrapper for the Cephes [1]_ routine `ellik`. The computation is
2648 carried out using the arithmetic-geometric mean algorithm.
2650 The parameterization in terms of :math:`m` follows that of section
2651 17.2 in [2]_. Other parameterizations in terms of the
2652 complementary parameter :math:`1 - m`, modular angle
2653 :math:`\sin^2(\alpha) = m`, or modulus :math:`k^2 = m` are also
2654 used, so be careful that you choose the correct parameter.
2656 The Legendre K incomplete integral (or F integral) is related to
2657 Carlson's symmetric R_F function [3]_.
2658 Setting :math:`c = \csc^2\phi`,
2660 .. math:: F(\phi, m) = R_F(c-1, c-k^2, c) .
2662 See Also
2663 --------
2664 ellipkm1 : Complete elliptic integral of the first kind, near `m` = 1
2665 ellipk : Complete elliptic integral of the first kind
2666 ellipe : Complete elliptic integral of the second kind
2667 ellipeinc : Incomplete elliptic integral of the second kind
2668 elliprf : Completely-symmetric elliptic integral of the first kind.
2670 References
2671 ----------
2672 .. [1] Cephes Mathematical Functions Library,
2673 http://www.netlib.org/cephes/
2674 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
2675 Handbook of Mathematical Functions with Formulas,
2676 Graphs, and Mathematical Tables. New York: Dover, 1972.
2677 .. [3] NIST Digital Library of Mathematical
2678 Functions. http://dlmf.nist.gov/, Release 1.0.28 of
2679 2020-09-15. See Sec. 19.25(i) https://dlmf.nist.gov/19.25#i
2680 """)
2682add_newdoc(
2683 "elliprc",
2684 r"""
2685 elliprc(x, y, out=None)
2687 Degenerate symmetric elliptic integral.
2689 The function RC is defined as [1]_
2691 .. math::
2693 R_{\mathrm{C}}(x, y) =
2694 \frac{1}{2} \int_0^{+\infty} (t + x)^{-1/2} (t + y)^{-1} dt
2695 = R_{\mathrm{F}}(x, y, y)
2697 Parameters
2698 ----------
2699 x, y : array_like
2700 Real or complex input parameters. `x` can be any number in the
2701 complex plane cut along the negative real axis. `y` must be non-zero.
2702 out : ndarray, optional
2703 Optional output array for the function values
2705 Returns
2706 -------
2707 R : scalar or ndarray
2708 Value of the integral. If `y` is real and negative, the Cauchy
2709 principal value is returned. If both of `x` and `y` are real, the
2710 return value is real. Otherwise, the return value is complex.
2712 Notes
2713 -----
2714 RC is a degenerate case of the symmetric integral RF: ``elliprc(x, y) ==
2715 elliprf(x, y, y)``. It is an elementary function rather than an elliptic
2716 integral.
2718 The code implements Carlson's algorithm based on the duplication theorems
2719 and series expansion up to the 7th order. [2]_
2721 .. versionadded:: 1.8.0
2723 See Also
2724 --------
2725 elliprf : Completely-symmetric elliptic integral of the first kind.
2726 elliprd : Symmetric elliptic integral of the second kind.
2727 elliprg : Completely-symmetric elliptic integral of the second kind.
2728 elliprj : Symmetric elliptic integral of the third kind.
2730 References
2731 ----------
2732 .. [1] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
2733 Functions," NIST, US Dept. of Commerce.
2734 https://dlmf.nist.gov/19.16.E6
2735 .. [2] B. C. Carlson, "Numerical computation of real or complex elliptic
2736 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
2737 https://arxiv.org/abs/math/9409227
2738 https://doi.org/10.1007/BF02198293
2740 Examples
2741 --------
2742 Basic homogeneity property:
2744 >>> import numpy as np
2745 >>> from scipy.special import elliprc
2747 >>> x = 1.2 + 3.4j
2748 >>> y = 5.
2749 >>> scale = 0.3 + 0.4j
2750 >>> elliprc(scale*x, scale*y)
2751 (0.5484493976710874-0.4169557678995833j)
2753 >>> elliprc(x, y)/np.sqrt(scale)
2754 (0.5484493976710874-0.41695576789958333j)
2756 When the two arguments coincide, the integral is particularly
2757 simple:
2759 >>> x = 1.2 + 3.4j
2760 >>> elliprc(x, x)
2761 (0.4299173120614631-0.3041729818745595j)
2763 >>> 1/np.sqrt(x)
2764 (0.4299173120614631-0.30417298187455954j)
2766 Another simple case: the first argument vanishes:
2768 >>> y = 1.2 + 3.4j
2769 >>> elliprc(0, y)
2770 (0.6753125346116815-0.47779380263880866j)
2772 >>> np.pi/2/np.sqrt(y)
2773 (0.6753125346116815-0.4777938026388088j)
2775 When `x` and `y` are both positive, we can express
2776 :math:`R_C(x,y)` in terms of more elementary functions. For the
2777 case :math:`0 \le x < y`,
2779 >>> x = 3.2
2780 >>> y = 6.
2781 >>> elliprc(x, y)
2782 0.44942991498453444
2784 >>> np.arctan(np.sqrt((y-x)/x))/np.sqrt(y-x)
2785 0.44942991498453433
2787 And for the case :math:`0 \le y < x`,
2789 >>> x = 6.
2790 >>> y = 3.2
2791 >>> elliprc(x,y)
2792 0.4989837501576147
2794 >>> np.log((np.sqrt(x)+np.sqrt(x-y))/np.sqrt(y))/np.sqrt(x-y)
2795 0.49898375015761476
2797 """)
2799add_newdoc(
2800 "elliprd",
2801 r"""
2802 elliprd(x, y, z, out=None)
2804 Symmetric elliptic integral of the second kind.
2806 The function RD is defined as [1]_
2808 .. math::
2810 R_{\mathrm{D}}(x, y, z) =
2811 \frac{3}{2} \int_0^{+\infty} [(t + x) (t + y)]^{-1/2} (t + z)^{-3/2}
2812 dt
2814 Parameters
2815 ----------
2816 x, y, z : array_like
2817 Real or complex input parameters. `x` or `y` can be any number in the
2818 complex plane cut along the negative real axis, but at most one of them
2819 can be zero, while `z` must be non-zero.
2820 out : ndarray, optional
2821 Optional output array for the function values
2823 Returns
2824 -------
2825 R : scalar or ndarray
2826 Value of the integral. If all of `x`, `y`, and `z` are real, the
2827 return value is real. Otherwise, the return value is complex.
2829 Notes
2830 -----
2831 RD is a degenerate case of the elliptic integral RJ: ``elliprd(x, y, z) ==
2832 elliprj(x, y, z, z)``.
2834 The code implements Carlson's algorithm based on the duplication theorems
2835 and series expansion up to the 7th order. [2]_
2837 .. versionadded:: 1.8.0
2839 See Also
2840 --------
2841 elliprc : Degenerate symmetric elliptic integral.
2842 elliprf : Completely-symmetric elliptic integral of the first kind.
2843 elliprg : Completely-symmetric elliptic integral of the second kind.
2844 elliprj : Symmetric elliptic integral of the third kind.
2846 References
2847 ----------
2848 .. [1] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
2849 Functions," NIST, US Dept. of Commerce.
2850 https://dlmf.nist.gov/19.16.E5
2851 .. [2] B. C. Carlson, "Numerical computation of real or complex elliptic
2852 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
2853 https://arxiv.org/abs/math/9409227
2854 https://doi.org/10.1007/BF02198293
2856 Examples
2857 --------
2858 Basic homogeneity property:
2860 >>> import numpy as np
2861 >>> from scipy.special import elliprd
2863 >>> x = 1.2 + 3.4j
2864 >>> y = 5.
2865 >>> z = 6.
2866 >>> scale = 0.3 + 0.4j
2867 >>> elliprd(scale*x, scale*y, scale*z)
2868 (-0.03703043835680379-0.24500934665683802j)
2870 >>> elliprd(x, y, z)*np.power(scale, -1.5)
2871 (-0.0370304383568038-0.24500934665683805j)
2873 All three arguments coincide:
2875 >>> x = 1.2 + 3.4j
2876 >>> elliprd(x, x, x)
2877 (-0.03986825876151896-0.14051741840449586j)
2879 >>> np.power(x, -1.5)
2880 (-0.03986825876151894-0.14051741840449583j)
2882 The so-called "second lemniscate constant":
2884 >>> elliprd(0, 2, 1)/3
2885 0.5990701173677961
2887 >>> from scipy.special import gamma
2888 >>> gamma(0.75)**2/np.sqrt(2*np.pi)
2889 0.5990701173677959
2891 """)
2893add_newdoc(
2894 "elliprf",
2895 r"""
2896 elliprf(x, y, z, out=None)
2898 Completely-symmetric elliptic integral of the first kind.
2900 The function RF is defined as [1]_
2902 .. math::
2904 R_{\mathrm{F}}(x, y, z) =
2905 \frac{1}{2} \int_0^{+\infty} [(t + x) (t + y) (t + z)]^{-1/2} dt
2907 Parameters
2908 ----------
2909 x, y, z : array_like
2910 Real or complex input parameters. `x`, `y`, or `z` can be any number in
2911 the complex plane cut along the negative real axis, but at most one of
2912 them can be zero.
2913 out : ndarray, optional
2914 Optional output array for the function values
2916 Returns
2917 -------
2918 R : scalar or ndarray
2919 Value of the integral. If all of `x`, `y`, and `z` are real, the return
2920 value is real. Otherwise, the return value is complex.
2922 Notes
2923 -----
2924 The code implements Carlson's algorithm based on the duplication theorems
2925 and series expansion up to the 7th order (cf.:
2926 https://dlmf.nist.gov/19.36.i) and the AGM algorithm for the complete
2927 integral. [2]_
2929 .. versionadded:: 1.8.0
2931 See Also
2932 --------
2933 elliprc : Degenerate symmetric integral.
2934 elliprd : Symmetric elliptic integral of the second kind.
2935 elliprg : Completely-symmetric elliptic integral of the second kind.
2936 elliprj : Symmetric elliptic integral of the third kind.
2938 References
2939 ----------
2940 .. [1] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
2941 Functions," NIST, US Dept. of Commerce.
2942 https://dlmf.nist.gov/19.16.E1
2943 .. [2] B. C. Carlson, "Numerical computation of real or complex elliptic
2944 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
2945 https://arxiv.org/abs/math/9409227
2946 https://doi.org/10.1007/BF02198293
2948 Examples
2949 --------
2950 Basic homogeneity property:
2952 >>> import numpy as np
2953 >>> from scipy.special import elliprf
2955 >>> x = 1.2 + 3.4j
2956 >>> y = 5.
2957 >>> z = 6.
2958 >>> scale = 0.3 + 0.4j
2959 >>> elliprf(scale*x, scale*y, scale*z)
2960 (0.5328051227278146-0.4008623567957094j)
2962 >>> elliprf(x, y, z)/np.sqrt(scale)
2963 (0.5328051227278147-0.4008623567957095j)
2965 All three arguments coincide:
2967 >>> x = 1.2 + 3.4j
2968 >>> elliprf(x, x, x)
2969 (0.42991731206146316-0.30417298187455954j)
2971 >>> 1/np.sqrt(x)
2972 (0.4299173120614631-0.30417298187455954j)
2974 The so-called "first lemniscate constant":
2976 >>> elliprf(0, 1, 2)
2977 1.3110287771460598
2979 >>> from scipy.special import gamma
2980 >>> gamma(0.25)**2/(4*np.sqrt(2*np.pi))
2981 1.3110287771460598
2983 """)
2985add_newdoc(
2986 "elliprg",
2987 r"""
2988 elliprg(x, y, z, out=None)
2990 Completely-symmetric elliptic integral of the second kind.
2992 The function RG is defined as [1]_
2994 .. math::
2996 R_{\mathrm{G}}(x, y, z) =
2997 \frac{1}{4} \int_0^{+\infty} [(t + x) (t + y) (t + z)]^{-1/2}
2998 \left(\frac{x}{t + x} + \frac{y}{t + y} + \frac{z}{t + z}\right) t
2999 dt
3001 Parameters
3002 ----------
3003 x, y, z : array_like
3004 Real or complex input parameters. `x`, `y`, or `z` can be any number in
3005 the complex plane cut along the negative real axis.
3006 out : ndarray, optional
3007 Optional output array for the function values
3009 Returns
3010 -------
3011 R : scalar or ndarray
3012 Value of the integral. If all of `x`, `y`, and `z` are real, the return
3013 value is real. Otherwise, the return value is complex.
3015 Notes
3016 -----
3017 The implementation uses the relation [1]_
3019 .. math::
3021 2 R_{\mathrm{G}}(x, y, z) =
3022 z R_{\mathrm{F}}(x, y, z) -
3023 \frac{1}{3} (x - z) (y - z) R_{\mathrm{D}}(x, y, z) +
3024 \sqrt{\frac{x y}{z}}
3026 and the symmetry of `x`, `y`, `z` when at least one non-zero parameter can
3027 be chosen as the pivot. When one of the arguments is close to zero, the AGM
3028 method is applied instead. Other special cases are computed following Ref.
3029 [2]_
3031 .. versionadded:: 1.8.0
3033 See Also
3034 --------
3035 elliprc : Degenerate symmetric integral.
3036 elliprd : Symmetric elliptic integral of the second kind.
3037 elliprf : Completely-symmetric elliptic integral of the first kind.
3038 elliprj : Symmetric elliptic integral of the third kind.
3040 References
3041 ----------
3042 .. [1] B. C. Carlson, "Numerical computation of real or complex elliptic
3043 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
3044 https://arxiv.org/abs/math/9409227
3045 https://doi.org/10.1007/BF02198293
3046 .. [2] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
3047 Functions," NIST, US Dept. of Commerce.
3048 https://dlmf.nist.gov/19.16.E1
3049 https://dlmf.nist.gov/19.20.ii
3051 Examples
3052 --------
3053 Basic homogeneity property:
3055 >>> import numpy as np
3056 >>> from scipy.special import elliprg
3058 >>> x = 1.2 + 3.4j
3059 >>> y = 5.
3060 >>> z = 6.
3061 >>> scale = 0.3 + 0.4j
3062 >>> elliprg(scale*x, scale*y, scale*z)
3063 (1.195936862005246+0.8470988320464167j)
3065 >>> elliprg(x, y, z)*np.sqrt(scale)
3066 (1.195936862005246+0.8470988320464165j)
3068 Simplifications:
3070 >>> elliprg(0, y, y)
3071 1.756203682760182
3073 >>> 0.25*np.pi*np.sqrt(y)
3074 1.7562036827601817
3076 >>> elliprg(0, 0, z)
3077 1.224744871391589
3079 >>> 0.5*np.sqrt(z)
3080 1.224744871391589
3082 The surface area of a triaxial ellipsoid with semiaxes ``a``, ``b``, and
3083 ``c`` is given by
3085 .. math::
3087 S = 4 \pi a b c R_{\mathrm{G}}(1 / a^2, 1 / b^2, 1 / c^2).
3089 >>> def ellipsoid_area(a, b, c):
3090 ... r = 4.0 * np.pi * a * b * c
3091 ... return r * elliprg(1.0 / (a * a), 1.0 / (b * b), 1.0 / (c * c))
3092 >>> print(ellipsoid_area(1, 3, 5))
3093 108.62688289491807
3094 """)
3096add_newdoc(
3097 "elliprj",
3098 r"""
3099 elliprj(x, y, z, p, out=None)
3101 Symmetric elliptic integral of the third kind.
3103 The function RJ is defined as [1]_
3105 .. math::
3107 R_{\mathrm{J}}(x, y, z, p) =
3108 \frac{3}{2} \int_0^{+\infty} [(t + x) (t + y) (t + z)]^{-1/2}
3109 (t + p)^{-1} dt
3111 .. warning::
3112 This function should be considered experimental when the inputs are
3113 unbalanced. Check correctness with another independent implementation.
3115 Parameters
3116 ----------
3117 x, y, z, p : array_like
3118 Real or complex input parameters. `x`, `y`, or `z` are numbers in
3119 the complex plane cut along the negative real axis (subject to further
3120 constraints, see Notes), and at most one of them can be zero. `p` must
3121 be non-zero.
3122 out : ndarray, optional
3123 Optional output array for the function values
3125 Returns
3126 -------
3127 R : scalar or ndarray
3128 Value of the integral. If all of `x`, `y`, `z`, and `p` are real, the
3129 return value is real. Otherwise, the return value is complex.
3131 If `p` is real and negative, while `x`, `y`, and `z` are real,
3132 non-negative, and at most one of them is zero, the Cauchy principal
3133 value is returned. [1]_ [2]_
3135 Notes
3136 -----
3137 The code implements Carlson's algorithm based on the duplication theorems
3138 and series expansion up to the 7th order. [3]_ The algorithm is slightly
3139 different from its earlier incarnation as it appears in [1]_, in that the
3140 call to `elliprc` (or ``atan``/``atanh``, see [4]_) is no longer needed in
3141 the inner loop. Asymptotic approximations are used where arguments differ
3142 widely in the order of magnitude. [5]_
3144 The input values are subject to certain sufficient but not necessary
3145 constaints when input arguments are complex. Notably, ``x``, ``y``, and
3146 ``z`` must have non-negative real parts, unless two of them are
3147 non-negative and complex-conjugates to each other while the other is a real
3148 non-negative number. [1]_ If the inputs do not satisfy the sufficient
3149 condition described in Ref. [1]_ they are rejected outright with the output
3150 set to NaN.
3152 In the case where one of ``x``, ``y``, and ``z`` is equal to ``p``, the
3153 function ``elliprd`` should be preferred because of its less restrictive
3154 domain.
3156 .. versionadded:: 1.8.0
3158 See Also
3159 --------
3160 elliprc : Degenerate symmetric integral.
3161 elliprd : Symmetric elliptic integral of the second kind.
3162 elliprf : Completely-symmetric elliptic integral of the first kind.
3163 elliprg : Completely-symmetric elliptic integral of the second kind.
3165 References
3166 ----------
3167 .. [1] B. C. Carlson, "Numerical computation of real or complex elliptic
3168 integrals," Numer. Algorithm, vol. 10, no. 1, pp. 13-26, 1995.
3169 https://arxiv.org/abs/math/9409227
3170 https://doi.org/10.1007/BF02198293
3171 .. [2] B. C. Carlson, ed., Chapter 19 in "Digital Library of Mathematical
3172 Functions," NIST, US Dept. of Commerce.
3173 https://dlmf.nist.gov/19.20.iii
3174 .. [3] B. C. Carlson, J. FitzSimmons, "Reduction Theorems for Elliptic
3175 Integrands with the Square Root of Two Quadratic Factors," J.
3176 Comput. Appl. Math., vol. 118, nos. 1-2, pp. 71-85, 2000.
3177 https://doi.org/10.1016/S0377-0427(00)00282-X
3178 .. [4] F. Johansson, "Numerical Evaluation of Elliptic Functions, Elliptic
3179 Integrals and Modular Forms," in J. Blumlein, C. Schneider, P.
3180 Paule, eds., "Elliptic Integrals, Elliptic Functions and Modular
3181 Forms in Quantum Field Theory," pp. 269-293, 2019 (Cham,
3182 Switzerland: Springer Nature Switzerland)
3183 https://arxiv.org/abs/1806.06725
3184 https://doi.org/10.1007/978-3-030-04480-0
3185 .. [5] B. C. Carlson, J. L. Gustafson, "Asymptotic Approximations for
3186 Symmetric Elliptic Integrals," SIAM J. Math. Anls., vol. 25, no. 2,
3187 pp. 288-303, 1994.
3188 https://arxiv.org/abs/math/9310223
3189 https://doi.org/10.1137/S0036141092228477
3191 Examples
3192 --------
3193 Basic homogeneity property:
3195 >>> import numpy as np
3196 >>> from scipy.special import elliprj
3198 >>> x = 1.2 + 3.4j
3199 >>> y = 5.
3200 >>> z = 6.
3201 >>> p = 7.
3202 >>> scale = 0.3 - 0.4j
3203 >>> elliprj(scale*x, scale*y, scale*z, scale*p)
3204 (0.10834905565679157+0.19694950747103812j)
3206 >>> elliprj(x, y, z, p)*np.power(scale, -1.5)
3207 (0.10834905565679556+0.19694950747103854j)
3209 Reduction to simpler elliptic integral:
3211 >>> elliprj(x, y, z, z)
3212 (0.08288462362195129-0.028376809745123258j)
3214 >>> from scipy.special import elliprd
3215 >>> elliprd(x, y, z)
3216 (0.08288462362195136-0.028376809745123296j)
3218 All arguments coincide:
3220 >>> elliprj(x, x, x, x)
3221 (-0.03986825876151896-0.14051741840449586j)
3223 >>> np.power(x, -1.5)
3224 (-0.03986825876151894-0.14051741840449583j)
3226 """)
3228add_newdoc("entr",
3229 r"""
3230 entr(x, out=None)
3232 Elementwise function for computing entropy.
3234 .. math:: \text{entr}(x) = \begin{cases} - x \log(x) & x > 0 \\ 0 & x = 0 \\ -\infty & \text{otherwise} \end{cases}
3236 Parameters
3237 ----------
3238 x : ndarray
3239 Input array.
3240 out : ndarray, optional
3241 Optional output array for the function values
3243 Returns
3244 -------
3245 res : scalar or ndarray
3246 The value of the elementwise entropy function at the given points `x`.
3248 See Also
3249 --------
3250 kl_div, rel_entr, scipy.stats.entropy
3252 Notes
3253 -----
3254 .. versionadded:: 0.15.0
3256 This function is concave.
3258 The origin of this function is in convex programming; see [1]_.
3259 Given a probability distribution :math:`p_1, \ldots, p_n`,
3260 the definition of entropy in the context of *information theory* is
3262 .. math::
3264 \sum_{i = 1}^n \mathrm{entr}(p_i).
3266 To compute the latter quantity, use `scipy.stats.entropy`.
3268 References
3269 ----------
3270 .. [1] Boyd, Stephen and Lieven Vandenberghe. *Convex optimization*.
3271 Cambridge University Press, 2004.
3272 :doi:`https://doi.org/10.1017/CBO9780511804441`
3274 """)
3276add_newdoc("erf",
3277 """
3278 erf(z, out=None)
3280 Returns the error function of complex argument.
3282 It is defined as ``2/sqrt(pi)*integral(exp(-t**2), t=0..z)``.
3284 Parameters
3285 ----------
3286 x : ndarray
3287 Input array.
3288 out : ndarray, optional
3289 Optional output array for the function values
3291 Returns
3292 -------
3293 res : scalar or ndarray
3294 The values of the error function at the given points `x`.
3296 See Also
3297 --------
3298 erfc, erfinv, erfcinv, wofz, erfcx, erfi
3300 Notes
3301 -----
3302 The cumulative of the unit normal distribution is given by
3303 ``Phi(z) = 1/2[1 + erf(z/sqrt(2))]``.
3305 References
3306 ----------
3307 .. [1] https://en.wikipedia.org/wiki/Error_function
3308 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
3309 Handbook of Mathematical Functions with Formulas,
3310 Graphs, and Mathematical Tables. New York: Dover,
3311 1972. http://www.math.sfu.ca/~cbm/aands/page_297.htm
3312 .. [3] Steven G. Johnson, Faddeeva W function implementation.
3313 http://ab-initio.mit.edu/Faddeeva
3315 Examples
3316 --------
3317 >>> import numpy as np
3318 >>> from scipy import special
3319 >>> import matplotlib.pyplot as plt
3320 >>> x = np.linspace(-3, 3)
3321 >>> plt.plot(x, special.erf(x))
3322 >>> plt.xlabel('$x$')
3323 >>> plt.ylabel('$erf(x)$')
3324 >>> plt.show()
3326 """)
3328add_newdoc("erfc",
3329 """
3330 erfc(x, out=None)
3332 Complementary error function, ``1 - erf(x)``.
3334 Parameters
3335 ----------
3336 x : array_like
3337 Real or complex valued argument
3338 out : ndarray, optional
3339 Optional output array for the function results
3341 Returns
3342 -------
3343 scalar or ndarray
3344 Values of the complementary error function
3346 See Also
3347 --------
3348 erf, erfi, erfcx, dawsn, wofz
3350 References
3351 ----------
3352 .. [1] Steven G. Johnson, Faddeeva W function implementation.
3353 http://ab-initio.mit.edu/Faddeeva
3355 Examples
3356 --------
3357 >>> import numpy as np
3358 >>> from scipy import special
3359 >>> import matplotlib.pyplot as plt
3360 >>> x = np.linspace(-3, 3)
3361 >>> plt.plot(x, special.erfc(x))
3362 >>> plt.xlabel('$x$')
3363 >>> plt.ylabel('$erfc(x)$')
3364 >>> plt.show()
3366 """)
3368add_newdoc("erfi",
3369 """
3370 erfi(z, out=None)
3372 Imaginary error function, ``-i erf(i z)``.
3374 Parameters
3375 ----------
3376 z : array_like
3377 Real or complex valued argument
3378 out : ndarray, optional
3379 Optional output array for the function results
3381 Returns
3382 -------
3383 scalar or ndarray
3384 Values of the imaginary error function
3386 See Also
3387 --------
3388 erf, erfc, erfcx, dawsn, wofz
3390 Notes
3391 -----
3393 .. versionadded:: 0.12.0
3395 References
3396 ----------
3397 .. [1] Steven G. Johnson, Faddeeva W function implementation.
3398 http://ab-initio.mit.edu/Faddeeva
3400 Examples
3401 --------
3402 >>> import numpy as np
3403 >>> from scipy import special
3404 >>> import matplotlib.pyplot as plt
3405 >>> x = np.linspace(-3, 3)
3406 >>> plt.plot(x, special.erfi(x))
3407 >>> plt.xlabel('$x$')
3408 >>> plt.ylabel('$erfi(x)$')
3409 >>> plt.show()
3411 """)
3413add_newdoc("erfcx",
3414 """
3415 erfcx(x, out=None)
3417 Scaled complementary error function, ``exp(x**2) * erfc(x)``.
3419 Parameters
3420 ----------
3421 x : array_like
3422 Real or complex valued argument
3423 out : ndarray, optional
3424 Optional output array for the function results
3426 Returns
3427 -------
3428 scalar or ndarray
3429 Values of the scaled complementary error function
3432 See Also
3433 --------
3434 erf, erfc, erfi, dawsn, wofz
3436 Notes
3437 -----
3439 .. versionadded:: 0.12.0
3441 References
3442 ----------
3443 .. [1] Steven G. Johnson, Faddeeva W function implementation.
3444 http://ab-initio.mit.edu/Faddeeva
3446 Examples
3447 --------
3448 >>> import numpy as np
3449 >>> from scipy import special
3450 >>> import matplotlib.pyplot as plt
3451 >>> x = np.linspace(-3, 3)
3452 >>> plt.plot(x, special.erfcx(x))
3453 >>> plt.xlabel('$x$')
3454 >>> plt.ylabel('$erfcx(x)$')
3455 >>> plt.show()
3457 """)
3459add_newdoc(
3460 "erfinv",
3461 """
3462 erfinv(y, out=None)
3464 Inverse of the error function.
3466 Computes the inverse of the error function.
3468 In the complex domain, there is no unique complex number w satisfying
3469 erf(w)=z. This indicates a true inverse function would be multivalued.
3470 When the domain restricts to the real, -1 < x < 1, there is a unique real
3471 number satisfying erf(erfinv(x)) = x.
3473 Parameters
3474 ----------
3475 y : ndarray
3476 Argument at which to evaluate. Domain: [-1, 1]
3477 out : ndarray, optional
3478 Optional output array for the function values
3480 Returns
3481 -------
3482 erfinv : scalar or ndarray
3483 The inverse of erf of y, element-wise
3485 See Also
3486 --------
3487 erf : Error function of a complex argument
3488 erfc : Complementary error function, ``1 - erf(x)``
3489 erfcinv : Inverse of the complementary error function
3491 Examples
3492 --------
3493 >>> import numpy as np
3494 >>> import matplotlib.pyplot as plt
3495 >>> from scipy.special import erfinv, erf
3497 >>> erfinv(0.5)
3498 0.4769362762044699
3500 >>> y = np.linspace(-1.0, 1.0, num=9)
3501 >>> x = erfinv(y)
3502 >>> x
3503 array([ -inf, -0.81341985, -0.47693628, -0.22531206, 0. ,
3504 0.22531206, 0.47693628, 0.81341985, inf])
3506 Verify that ``erf(erfinv(y))`` is ``y``.
3508 >>> erf(x)
3509 array([-1. , -0.75, -0.5 , -0.25, 0. , 0.25, 0.5 , 0.75, 1. ])
3511 Plot the function:
3513 >>> y = np.linspace(-1, 1, 200)
3514 >>> fig, ax = plt.subplots()
3515 >>> ax.plot(y, erfinv(y))
3516 >>> ax.grid(True)
3517 >>> ax.set_xlabel('y')
3518 >>> ax.set_title('erfinv(y)')
3519 >>> plt.show()
3521 """)
3523add_newdoc(
3524 "erfcinv",
3525 """
3526 erfcinv(y, out=None)
3528 Inverse of the complementary error function.
3530 Computes the inverse of the complementary error function.
3532 In the complex domain, there is no unique complex number w satisfying
3533 erfc(w)=z. This indicates a true inverse function would be multivalued.
3534 When the domain restricts to the real, 0 < x < 2, there is a unique real
3535 number satisfying erfc(erfcinv(x)) = erfcinv(erfc(x)).
3537 It is related to inverse of the error function by erfcinv(1-x) = erfinv(x)
3539 Parameters
3540 ----------
3541 y : ndarray
3542 Argument at which to evaluate. Domain: [0, 2]
3543 out : ndarray, optional
3544 Optional output array for the function values
3546 Returns
3547 -------
3548 erfcinv : scalar or ndarray
3549 The inverse of erfc of y, element-wise
3551 See Also
3552 --------
3553 erf : Error function of a complex argument
3554 erfc : Complementary error function, ``1 - erf(x)``
3555 erfinv : Inverse of the error function
3557 Examples
3558 --------
3559 >>> import numpy as np
3560 >>> import matplotlib.pyplot as plt
3561 >>> from scipy.special import erfcinv
3563 >>> erfcinv(0.5)
3564 0.4769362762044699
3566 >>> y = np.linspace(0.0, 2.0, num=11)
3567 >>> erfcinv(y)
3568 array([ inf, 0.9061938 , 0.59511608, 0.37080716, 0.17914345,
3569 -0. , -0.17914345, -0.37080716, -0.59511608, -0.9061938 ,
3570 -inf])
3572 Plot the function:
3574 >>> y = np.linspace(0, 2, 200)
3575 >>> fig, ax = plt.subplots()
3576 >>> ax.plot(y, erfcinv(y))
3577 >>> ax.grid(True)
3578 >>> ax.set_xlabel('y')
3579 >>> ax.set_title('erfcinv(y)')
3580 >>> plt.show()
3582 """)
3584add_newdoc("eval_jacobi",
3585 r"""
3586 eval_jacobi(n, alpha, beta, x, out=None)
3588 Evaluate Jacobi polynomial at a point.
3590 The Jacobi polynomials can be defined via the Gauss hypergeometric
3591 function :math:`{}_2F_1` as
3593 .. math::
3595 P_n^{(\alpha, \beta)}(x) = \frac{(\alpha + 1)_n}{\Gamma(n + 1)}
3596 {}_2F_1(-n, 1 + \alpha + \beta + n; \alpha + 1; (1 - z)/2)
3598 where :math:`(\cdot)_n` is the Pochhammer symbol; see `poch`. When
3599 :math:`n` is an integer the result is a polynomial of degree
3600 :math:`n`. See 22.5.42 in [AS]_ for details.
3602 Parameters
3603 ----------
3604 n : array_like
3605 Degree of the polynomial. If not an integer the result is
3606 determined via the relation to the Gauss hypergeometric
3607 function.
3608 alpha : array_like
3609 Parameter
3610 beta : array_like
3611 Parameter
3612 x : array_like
3613 Points at which to evaluate the polynomial
3614 out : ndarray, optional
3615 Optional output array for the function values
3617 Returns
3618 -------
3619 P : scalar or ndarray
3620 Values of the Jacobi polynomial
3622 See Also
3623 --------
3624 roots_jacobi : roots and quadrature weights of Jacobi polynomials
3625 jacobi : Jacobi polynomial object
3626 hyp2f1 : Gauss hypergeometric function
3628 References
3629 ----------
3630 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3631 Handbook of Mathematical Functions with Formulas,
3632 Graphs, and Mathematical Tables. New York: Dover, 1972.
3634 """)
3636add_newdoc("eval_sh_jacobi",
3637 r"""
3638 eval_sh_jacobi(n, p, q, x, out=None)
3640 Evaluate shifted Jacobi polynomial at a point.
3642 Defined by
3644 .. math::
3646 G_n^{(p, q)}(x)
3647 = \binom{2n + p - 1}{n}^{-1} P_n^{(p - q, q - 1)}(2x - 1),
3649 where :math:`P_n^{(\cdot, \cdot)}` is the n-th Jacobi
3650 polynomial. See 22.5.2 in [AS]_ for details.
3652 Parameters
3653 ----------
3654 n : int
3655 Degree of the polynomial. If not an integer, the result is
3656 determined via the relation to `binom` and `eval_jacobi`.
3657 p : float
3658 Parameter
3659 q : float
3660 Parameter
3661 out : ndarray, optional
3662 Optional output array for the function values
3664 Returns
3665 -------
3666 G : scalar or ndarray
3667 Values of the shifted Jacobi polynomial.
3669 See Also
3670 --------
3671 roots_sh_jacobi : roots and quadrature weights of shifted Jacobi
3672 polynomials
3673 sh_jacobi : shifted Jacobi polynomial object
3674 eval_jacobi : evaluate Jacobi polynomials
3676 References
3677 ----------
3678 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3679 Handbook of Mathematical Functions with Formulas,
3680 Graphs, and Mathematical Tables. New York: Dover, 1972.
3682 """)
3684add_newdoc("eval_gegenbauer",
3685 r"""
3686 eval_gegenbauer(n, alpha, x, out=None)
3688 Evaluate Gegenbauer polynomial at a point.
3690 The Gegenbauer polynomials can be defined via the Gauss
3691 hypergeometric function :math:`{}_2F_1` as
3693 .. math::
3695 C_n^{(\alpha)} = \frac{(2\alpha)_n}{\Gamma(n + 1)}
3696 {}_2F_1(-n, 2\alpha + n; \alpha + 1/2; (1 - z)/2).
3698 When :math:`n` is an integer the result is a polynomial of degree
3699 :math:`n`. See 22.5.46 in [AS]_ for details.
3701 Parameters
3702 ----------
3703 n : array_like
3704 Degree of the polynomial. If not an integer, the result is
3705 determined via the relation to the Gauss hypergeometric
3706 function.
3707 alpha : array_like
3708 Parameter
3709 x : array_like
3710 Points at which to evaluate the Gegenbauer polynomial
3711 out : ndarray, optional
3712 Optional output array for the function values
3714 Returns
3715 -------
3716 C : scalar or ndarray
3717 Values of the Gegenbauer polynomial
3719 See Also
3720 --------
3721 roots_gegenbauer : roots and quadrature weights of Gegenbauer
3722 polynomials
3723 gegenbauer : Gegenbauer polynomial object
3724 hyp2f1 : Gauss hypergeometric function
3726 References
3727 ----------
3728 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3729 Handbook of Mathematical Functions with Formulas,
3730 Graphs, and Mathematical Tables. New York: Dover, 1972.
3732 """)
3734add_newdoc("eval_chebyt",
3735 r"""
3736 eval_chebyt(n, x, out=None)
3738 Evaluate Chebyshev polynomial of the first kind at a point.
3740 The Chebyshev polynomials of the first kind can be defined via the
3741 Gauss hypergeometric function :math:`{}_2F_1` as
3743 .. math::
3745 T_n(x) = {}_2F_1(n, -n; 1/2; (1 - x)/2).
3747 When :math:`n` is an integer the result is a polynomial of degree
3748 :math:`n`. See 22.5.47 in [AS]_ for details.
3750 Parameters
3751 ----------
3752 n : array_like
3753 Degree of the polynomial. If not an integer, the result is
3754 determined via the relation to the Gauss hypergeometric
3755 function.
3756 x : array_like
3757 Points at which to evaluate the Chebyshev polynomial
3758 out : ndarray, optional
3759 Optional output array for the function values
3761 Returns
3762 -------
3763 T : scalar or ndarray
3764 Values of the Chebyshev polynomial
3766 See Also
3767 --------
3768 roots_chebyt : roots and quadrature weights of Chebyshev
3769 polynomials of the first kind
3770 chebyu : Chebychev polynomial object
3771 eval_chebyu : evaluate Chebyshev polynomials of the second kind
3772 hyp2f1 : Gauss hypergeometric function
3773 numpy.polynomial.chebyshev.Chebyshev : Chebyshev series
3775 Notes
3776 -----
3777 This routine is numerically stable for `x` in ``[-1, 1]`` at least
3778 up to order ``10000``.
3780 References
3781 ----------
3782 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3783 Handbook of Mathematical Functions with Formulas,
3784 Graphs, and Mathematical Tables. New York: Dover, 1972.
3786 """)
3788add_newdoc("eval_chebyu",
3789 r"""
3790 eval_chebyu(n, x, out=None)
3792 Evaluate Chebyshev polynomial of the second kind at a point.
3794 The Chebyshev polynomials of the second kind can be defined via
3795 the Gauss hypergeometric function :math:`{}_2F_1` as
3797 .. math::
3799 U_n(x) = (n + 1) {}_2F_1(-n, n + 2; 3/2; (1 - x)/2).
3801 When :math:`n` is an integer the result is a polynomial of degree
3802 :math:`n`. See 22.5.48 in [AS]_ for details.
3804 Parameters
3805 ----------
3806 n : array_like
3807 Degree of the polynomial. If not an integer, the result is
3808 determined via the relation to the Gauss hypergeometric
3809 function.
3810 x : array_like
3811 Points at which to evaluate the Chebyshev polynomial
3812 out : ndarray, optional
3813 Optional output array for the function values
3815 Returns
3816 -------
3817 U : scalar or ndarray
3818 Values of the Chebyshev polynomial
3820 See Also
3821 --------
3822 roots_chebyu : roots and quadrature weights of Chebyshev
3823 polynomials of the second kind
3824 chebyu : Chebyshev polynomial object
3825 eval_chebyt : evaluate Chebyshev polynomials of the first kind
3826 hyp2f1 : Gauss hypergeometric function
3828 References
3829 ----------
3830 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3831 Handbook of Mathematical Functions with Formulas,
3832 Graphs, and Mathematical Tables. New York: Dover, 1972.
3834 """)
3836add_newdoc("eval_chebys",
3837 r"""
3838 eval_chebys(n, x, out=None)
3840 Evaluate Chebyshev polynomial of the second kind on [-2, 2] at a
3841 point.
3843 These polynomials are defined as
3845 .. math::
3847 S_n(x) = U_n(x/2)
3849 where :math:`U_n` is a Chebyshev polynomial of the second
3850 kind. See 22.5.13 in [AS]_ for details.
3852 Parameters
3853 ----------
3854 n : array_like
3855 Degree of the polynomial. If not an integer, the result is
3856 determined via the relation to `eval_chebyu`.
3857 x : array_like
3858 Points at which to evaluate the Chebyshev polynomial
3859 out : ndarray, optional
3860 Optional output array for the function values
3862 Returns
3863 -------
3864 S : scalar or ndarray
3865 Values of the Chebyshev polynomial
3867 See Also
3868 --------
3869 roots_chebys : roots and quadrature weights of Chebyshev
3870 polynomials of the second kind on [-2, 2]
3871 chebys : Chebyshev polynomial object
3872 eval_chebyu : evaluate Chebyshev polynomials of the second kind
3874 References
3875 ----------
3876 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3877 Handbook of Mathematical Functions with Formulas,
3878 Graphs, and Mathematical Tables. New York: Dover, 1972.
3880 Examples
3881 --------
3882 >>> import numpy as np
3883 >>> import scipy.special as sc
3885 They are a scaled version of the Chebyshev polynomials of the
3886 second kind.
3888 >>> x = np.linspace(-2, 2, 6)
3889 >>> sc.eval_chebys(3, x)
3890 array([-4. , 0.672, 0.736, -0.736, -0.672, 4. ])
3891 >>> sc.eval_chebyu(3, x / 2)
3892 array([-4. , 0.672, 0.736, -0.736, -0.672, 4. ])
3894 """)
3896add_newdoc("eval_chebyc",
3897 r"""
3898 eval_chebyc(n, x, out=None)
3900 Evaluate Chebyshev polynomial of the first kind on [-2, 2] at a
3901 point.
3903 These polynomials are defined as
3905 .. math::
3907 C_n(x) = 2 T_n(x/2)
3909 where :math:`T_n` is a Chebyshev polynomial of the first kind. See
3910 22.5.11 in [AS]_ for details.
3912 Parameters
3913 ----------
3914 n : array_like
3915 Degree of the polynomial. If not an integer, the result is
3916 determined via the relation to `eval_chebyt`.
3917 x : array_like
3918 Points at which to evaluate the Chebyshev polynomial
3919 out : ndarray, optional
3920 Optional output array for the function values
3922 Returns
3923 -------
3924 C : scalar or ndarray
3925 Values of the Chebyshev polynomial
3927 See Also
3928 --------
3929 roots_chebyc : roots and quadrature weights of Chebyshev
3930 polynomials of the first kind on [-2, 2]
3931 chebyc : Chebyshev polynomial object
3932 numpy.polynomial.chebyshev.Chebyshev : Chebyshev series
3933 eval_chebyt : evaluate Chebycshev polynomials of the first kind
3935 References
3936 ----------
3937 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3938 Handbook of Mathematical Functions with Formulas,
3939 Graphs, and Mathematical Tables. New York: Dover, 1972.
3941 Examples
3942 --------
3943 >>> import numpy as np
3944 >>> import scipy.special as sc
3946 They are a scaled version of the Chebyshev polynomials of the
3947 first kind.
3949 >>> x = np.linspace(-2, 2, 6)
3950 >>> sc.eval_chebyc(3, x)
3951 array([-2. , 1.872, 1.136, -1.136, -1.872, 2. ])
3952 >>> 2 * sc.eval_chebyt(3, x / 2)
3953 array([-2. , 1.872, 1.136, -1.136, -1.872, 2. ])
3955 """)
3957add_newdoc("eval_sh_chebyt",
3958 r"""
3959 eval_sh_chebyt(n, x, out=None)
3961 Evaluate shifted Chebyshev polynomial of the first kind at a
3962 point.
3964 These polynomials are defined as
3966 .. math::
3968 T_n^*(x) = T_n(2x - 1)
3970 where :math:`T_n` is a Chebyshev polynomial of the first kind. See
3971 22.5.14 in [AS]_ for details.
3973 Parameters
3974 ----------
3975 n : array_like
3976 Degree of the polynomial. If not an integer, the result is
3977 determined via the relation to `eval_chebyt`.
3978 x : array_like
3979 Points at which to evaluate the shifted Chebyshev polynomial
3980 out : ndarray, optional
3981 Optional output array for the function values
3983 Returns
3984 -------
3985 T : scalar or ndarray
3986 Values of the shifted Chebyshev polynomial
3988 See Also
3989 --------
3990 roots_sh_chebyt : roots and quadrature weights of shifted
3991 Chebyshev polynomials of the first kind
3992 sh_chebyt : shifted Chebyshev polynomial object
3993 eval_chebyt : evaluate Chebyshev polynomials of the first kind
3994 numpy.polynomial.chebyshev.Chebyshev : Chebyshev series
3996 References
3997 ----------
3998 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
3999 Handbook of Mathematical Functions with Formulas,
4000 Graphs, and Mathematical Tables. New York: Dover, 1972.
4002 """)
4004add_newdoc("eval_sh_chebyu",
4005 r"""
4006 eval_sh_chebyu(n, x, out=None)
4008 Evaluate shifted Chebyshev polynomial of the second kind at a
4009 point.
4011 These polynomials are defined as
4013 .. math::
4015 U_n^*(x) = U_n(2x - 1)
4017 where :math:`U_n` is a Chebyshev polynomial of the first kind. See
4018 22.5.15 in [AS]_ for details.
4020 Parameters
4021 ----------
4022 n : array_like
4023 Degree of the polynomial. If not an integer, the result is
4024 determined via the relation to `eval_chebyu`.
4025 x : array_like
4026 Points at which to evaluate the shifted Chebyshev polynomial
4027 out : ndarray, optional
4028 Optional output array for the function values
4030 Returns
4031 -------
4032 U : scalar or ndarray
4033 Values of the shifted Chebyshev polynomial
4035 See Also
4036 --------
4037 roots_sh_chebyu : roots and quadrature weights of shifted
4038 Chebychev polynomials of the second kind
4039 sh_chebyu : shifted Chebyshev polynomial object
4040 eval_chebyu : evaluate Chebyshev polynomials of the second kind
4042 References
4043 ----------
4044 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4045 Handbook of Mathematical Functions with Formulas,
4046 Graphs, and Mathematical Tables. New York: Dover, 1972.
4048 """)
4050add_newdoc("eval_legendre",
4051 r"""
4052 eval_legendre(n, x, out=None)
4054 Evaluate Legendre polynomial at a point.
4056 The Legendre polynomials can be defined via the Gauss
4057 hypergeometric function :math:`{}_2F_1` as
4059 .. math::
4061 P_n(x) = {}_2F_1(-n, n + 1; 1; (1 - x)/2).
4063 When :math:`n` is an integer the result is a polynomial of degree
4064 :math:`n`. See 22.5.49 in [AS]_ for details.
4066 Parameters
4067 ----------
4068 n : array_like
4069 Degree of the polynomial. If not an integer, the result is
4070 determined via the relation to the Gauss hypergeometric
4071 function.
4072 x : array_like
4073 Points at which to evaluate the Legendre polynomial
4074 out : ndarray, optional
4075 Optional output array for the function values
4077 Returns
4078 -------
4079 P : scalar or ndarray
4080 Values of the Legendre polynomial
4082 See Also
4083 --------
4084 roots_legendre : roots and quadrature weights of Legendre
4085 polynomials
4086 legendre : Legendre polynomial object
4087 hyp2f1 : Gauss hypergeometric function
4088 numpy.polynomial.legendre.Legendre : Legendre series
4090 References
4091 ----------
4092 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4093 Handbook of Mathematical Functions with Formulas,
4094 Graphs, and Mathematical Tables. New York: Dover, 1972.
4096 Examples
4097 --------
4098 >>> import numpy as np
4099 >>> from scipy.special import eval_legendre
4101 Evaluate the zero-order Legendre polynomial at x = 0
4103 >>> eval_legendre(0, 0)
4104 1.0
4106 Evaluate the first-order Legendre polynomial between -1 and 1
4108 >>> X = np.linspace(-1, 1, 5) # Domain of Legendre polynomials
4109 >>> eval_legendre(1, X)
4110 array([-1. , -0.5, 0. , 0.5, 1. ])
4112 Evaluate Legendre polynomials of order 0 through 4 at x = 0
4114 >>> N = range(0, 5)
4115 >>> eval_legendre(N, 0)
4116 array([ 1. , 0. , -0.5 , 0. , 0.375])
4118 Plot Legendre polynomials of order 0 through 4
4120 >>> X = np.linspace(-1, 1)
4122 >>> import matplotlib.pyplot as plt
4123 >>> for n in range(0, 5):
4124 ... y = eval_legendre(n, X)
4125 ... plt.plot(X, y, label=r'$P_{}(x)$'.format(n))
4127 >>> plt.title("Legendre Polynomials")
4128 >>> plt.xlabel("x")
4129 >>> plt.ylabel(r'$P_n(x)$')
4130 >>> plt.legend(loc='lower right')
4131 >>> plt.show()
4133 """)
4135add_newdoc("eval_sh_legendre",
4136 r"""
4137 eval_sh_legendre(n, x, out=None)
4139 Evaluate shifted Legendre polynomial at a point.
4141 These polynomials are defined as
4143 .. math::
4145 P_n^*(x) = P_n(2x - 1)
4147 where :math:`P_n` is a Legendre polynomial. See 2.2.11 in [AS]_
4148 for details.
4150 Parameters
4151 ----------
4152 n : array_like
4153 Degree of the polynomial. If not an integer, the value is
4154 determined via the relation to `eval_legendre`.
4155 x : array_like
4156 Points at which to evaluate the shifted Legendre polynomial
4157 out : ndarray, optional
4158 Optional output array for the function values
4160 Returns
4161 -------
4162 P : scalar or ndarray
4163 Values of the shifted Legendre polynomial
4165 See Also
4166 --------
4167 roots_sh_legendre : roots and quadrature weights of shifted
4168 Legendre polynomials
4169 sh_legendre : shifted Legendre polynomial object
4170 eval_legendre : evaluate Legendre polynomials
4171 numpy.polynomial.legendre.Legendre : Legendre series
4173 References
4174 ----------
4175 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4176 Handbook of Mathematical Functions with Formulas,
4177 Graphs, and Mathematical Tables. New York: Dover, 1972.
4179 """)
4181add_newdoc("eval_genlaguerre",
4182 r"""
4183 eval_genlaguerre(n, alpha, x, out=None)
4185 Evaluate generalized Laguerre polynomial at a point.
4187 The generalized Laguerre polynomials can be defined via the
4188 confluent hypergeometric function :math:`{}_1F_1` as
4190 .. math::
4192 L_n^{(\alpha)}(x) = \binom{n + \alpha}{n}
4193 {}_1F_1(-n, \alpha + 1, x).
4195 When :math:`n` is an integer the result is a polynomial of degree
4196 :math:`n`. See 22.5.54 in [AS]_ for details. The Laguerre
4197 polynomials are the special case where :math:`\alpha = 0`.
4199 Parameters
4200 ----------
4201 n : array_like
4202 Degree of the polynomial. If not an integer, the result is
4203 determined via the relation to the confluent hypergeometric
4204 function.
4205 alpha : array_like
4206 Parameter; must have ``alpha > -1``
4207 x : array_like
4208 Points at which to evaluate the generalized Laguerre
4209 polynomial
4210 out : ndarray, optional
4211 Optional output array for the function values
4213 Returns
4214 -------
4215 L : scalar or ndarray
4216 Values of the generalized Laguerre polynomial
4218 See Also
4219 --------
4220 roots_genlaguerre : roots and quadrature weights of generalized
4221 Laguerre polynomials
4222 genlaguerre : generalized Laguerre polynomial object
4223 hyp1f1 : confluent hypergeometric function
4224 eval_laguerre : evaluate Laguerre polynomials
4226 References
4227 ----------
4228 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4229 Handbook of Mathematical Functions with Formulas,
4230 Graphs, and Mathematical Tables. New York: Dover, 1972.
4232 """)
4234add_newdoc("eval_laguerre",
4235 r"""
4236 eval_laguerre(n, x, out=None)
4238 Evaluate Laguerre polynomial at a point.
4240 The Laguerre polynomials can be defined via the confluent
4241 hypergeometric function :math:`{}_1F_1` as
4243 .. math::
4245 L_n(x) = {}_1F_1(-n, 1, x).
4247 See 22.5.16 and 22.5.54 in [AS]_ for details. When :math:`n` is an
4248 integer the result is a polynomial of degree :math:`n`.
4250 Parameters
4251 ----------
4252 n : array_like
4253 Degree of the polynomial. If not an integer the result is
4254 determined via the relation to the confluent hypergeometric
4255 function.
4256 x : array_like
4257 Points at which to evaluate the Laguerre polynomial
4258 out : ndarray, optional
4259 Optional output array for the function values
4261 Returns
4262 -------
4263 L : scalar or ndarray
4264 Values of the Laguerre polynomial
4266 See Also
4267 --------
4268 roots_laguerre : roots and quadrature weights of Laguerre
4269 polynomials
4270 laguerre : Laguerre polynomial object
4271 numpy.polynomial.laguerre.Laguerre : Laguerre series
4272 eval_genlaguerre : evaluate generalized Laguerre polynomials
4274 References
4275 ----------
4276 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4277 Handbook of Mathematical Functions with Formulas,
4278 Graphs, and Mathematical Tables. New York: Dover, 1972.
4280 """)
4282add_newdoc("eval_hermite",
4283 r"""
4284 eval_hermite(n, x, out=None)
4286 Evaluate physicist's Hermite polynomial at a point.
4288 Defined by
4290 .. math::
4292 H_n(x) = (-1)^n e^{x^2} \frac{d^n}{dx^n} e^{-x^2};
4294 :math:`H_n` is a polynomial of degree :math:`n`. See 22.11.7 in
4295 [AS]_ for details.
4297 Parameters
4298 ----------
4299 n : array_like
4300 Degree of the polynomial
4301 x : array_like
4302 Points at which to evaluate the Hermite polynomial
4303 out : ndarray, optional
4304 Optional output array for the function values
4306 Returns
4307 -------
4308 H : scalar or ndarray
4309 Values of the Hermite polynomial
4311 See Also
4312 --------
4313 roots_hermite : roots and quadrature weights of physicist's
4314 Hermite polynomials
4315 hermite : physicist's Hermite polynomial object
4316 numpy.polynomial.hermite.Hermite : Physicist's Hermite series
4317 eval_hermitenorm : evaluate Probabilist's Hermite polynomials
4319 References
4320 ----------
4321 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4322 Handbook of Mathematical Functions with Formulas,
4323 Graphs, and Mathematical Tables. New York: Dover, 1972.
4325 """)
4327add_newdoc("eval_hermitenorm",
4328 r"""
4329 eval_hermitenorm(n, x, out=None)
4331 Evaluate probabilist's (normalized) Hermite polynomial at a
4332 point.
4334 Defined by
4336 .. math::
4338 He_n(x) = (-1)^n e^{x^2/2} \frac{d^n}{dx^n} e^{-x^2/2};
4340 :math:`He_n` is a polynomial of degree :math:`n`. See 22.11.8 in
4341 [AS]_ for details.
4343 Parameters
4344 ----------
4345 n : array_like
4346 Degree of the polynomial
4347 x : array_like
4348 Points at which to evaluate the Hermite polynomial
4349 out : ndarray, optional
4350 Optional output array for the function values
4352 Returns
4353 -------
4354 He : scalar or ndarray
4355 Values of the Hermite polynomial
4357 See Also
4358 --------
4359 roots_hermitenorm : roots and quadrature weights of probabilist's
4360 Hermite polynomials
4361 hermitenorm : probabilist's Hermite polynomial object
4362 numpy.polynomial.hermite_e.HermiteE : Probabilist's Hermite series
4363 eval_hermite : evaluate physicist's Hermite polynomials
4365 References
4366 ----------
4367 .. [AS] Milton Abramowitz and Irene A. Stegun, eds.
4368 Handbook of Mathematical Functions with Formulas,
4369 Graphs, and Mathematical Tables. New York: Dover, 1972.
4371 """)
4373add_newdoc("exp1",
4374 r"""
4375 exp1(z, out=None)
4377 Exponential integral E1.
4379 For complex :math:`z \ne 0` the exponential integral can be defined as
4380 [1]_
4382 .. math::
4384 E_1(z) = \int_z^\infty \frac{e^{-t}}{t} dt,
4386 where the path of the integral does not cross the negative real
4387 axis or pass through the origin.
4389 Parameters
4390 ----------
4391 z: array_like
4392 Real or complex argument.
4393 out : ndarray, optional
4394 Optional output array for the function results
4396 Returns
4397 -------
4398 scalar or ndarray
4399 Values of the exponential integral E1
4401 See Also
4402 --------
4403 expi : exponential integral :math:`Ei`
4404 expn : generalization of :math:`E_1`
4406 Notes
4407 -----
4408 For :math:`x > 0` it is related to the exponential integral
4409 :math:`Ei` (see `expi`) via the relation
4411 .. math::
4413 E_1(x) = -Ei(-x).
4415 References
4416 ----------
4417 .. [1] Digital Library of Mathematical Functions, 6.2.1
4418 https://dlmf.nist.gov/6.2#E1
4420 Examples
4421 --------
4422 >>> import numpy as np
4423 >>> import scipy.special as sc
4425 It has a pole at 0.
4427 >>> sc.exp1(0)
4428 inf
4430 It has a branch cut on the negative real axis.
4432 >>> sc.exp1(-1)
4433 nan
4434 >>> sc.exp1(complex(-1, 0))
4435 (-1.8951178163559368-3.141592653589793j)
4436 >>> sc.exp1(complex(-1, -0.0))
4437 (-1.8951178163559368+3.141592653589793j)
4439 It approaches 0 along the positive real axis.
4441 >>> sc.exp1([1, 10, 100, 1000])
4442 array([2.19383934e-01, 4.15696893e-06, 3.68359776e-46, 0.00000000e+00])
4444 It is related to `expi`.
4446 >>> x = np.array([1, 2, 3, 4])
4447 >>> sc.exp1(x)
4448 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4449 >>> -sc.expi(-x)
4450 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4452 """)
4454add_newdoc("exp10",
4455 """
4456 exp10(x, out=None)
4458 Compute ``10**x`` element-wise.
4460 Parameters
4461 ----------
4462 x : array_like
4463 `x` must contain real numbers.
4464 out : ndarray, optional
4465 Optional output array for the function values
4467 Returns
4468 -------
4469 scalar or ndarray
4470 ``10**x``, computed element-wise.
4472 Examples
4473 --------
4474 >>> import numpy as np
4475 >>> from scipy.special import exp10
4477 >>> exp10(3)
4478 1000.0
4479 >>> x = np.array([[-1, -0.5, 0], [0.5, 1, 1.5]])
4480 >>> exp10(x)
4481 array([[ 0.1 , 0.31622777, 1. ],
4482 [ 3.16227766, 10. , 31.6227766 ]])
4484 """)
4486add_newdoc("exp2",
4487 """
4488 exp2(x, out=None)
4490 Compute ``2**x`` element-wise.
4492 Parameters
4493 ----------
4494 x : array_like
4495 `x` must contain real numbers.
4496 out : ndarray, optional
4497 Optional output array for the function values
4499 Returns
4500 -------
4501 scalar or ndarray
4502 ``2**x``, computed element-wise.
4504 Examples
4505 --------
4506 >>> import numpy as np
4507 >>> from scipy.special import exp2
4509 >>> exp2(3)
4510 8.0
4511 >>> x = np.array([[-1, -0.5, 0], [0.5, 1, 1.5]])
4512 >>> exp2(x)
4513 array([[ 0.5 , 0.70710678, 1. ],
4514 [ 1.41421356, 2. , 2.82842712]])
4515 """)
4517add_newdoc("expi",
4518 r"""
4519 expi(x, out=None)
4521 Exponential integral Ei.
4523 For real :math:`x`, the exponential integral is defined as [1]_
4525 .. math::
4527 Ei(x) = \int_{-\infty}^x \frac{e^t}{t} dt.
4529 For :math:`x > 0` the integral is understood as a Cauchy principal
4530 value.
4532 It is extended to the complex plane by analytic continuation of
4533 the function on the interval :math:`(0, \infty)`. The complex
4534 variant has a branch cut on the negative real axis.
4536 Parameters
4537 ----------
4538 x : array_like
4539 Real or complex valued argument
4540 out : ndarray, optional
4541 Optional output array for the function results
4543 Returns
4544 -------
4545 scalar or ndarray
4546 Values of the exponential integral
4548 Notes
4549 -----
4550 The exponential integrals :math:`E_1` and :math:`Ei` satisfy the
4551 relation
4553 .. math::
4555 E_1(x) = -Ei(-x)
4557 for :math:`x > 0`.
4559 See Also
4560 --------
4561 exp1 : Exponential integral :math:`E_1`
4562 expn : Generalized exponential integral :math:`E_n`
4564 References
4565 ----------
4566 .. [1] Digital Library of Mathematical Functions, 6.2.5
4567 https://dlmf.nist.gov/6.2#E5
4569 Examples
4570 --------
4571 >>> import numpy as np
4572 >>> import scipy.special as sc
4574 It is related to `exp1`.
4576 >>> x = np.array([1, 2, 3, 4])
4577 >>> -sc.expi(-x)
4578 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4579 >>> sc.exp1(x)
4580 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4582 The complex variant has a branch cut on the negative real axis.
4584 >>> sc.expi(-1 + 1e-12j)
4585 (-0.21938393439552062+3.1415926535894254j)
4586 >>> sc.expi(-1 - 1e-12j)
4587 (-0.21938393439552062-3.1415926535894254j)
4589 As the complex variant approaches the branch cut, the real parts
4590 approach the value of the real variant.
4592 >>> sc.expi(-1)
4593 -0.21938393439552062
4595 The SciPy implementation returns the real variant for complex
4596 values on the branch cut.
4598 >>> sc.expi(complex(-1, 0.0))
4599 (-0.21938393439552062-0j)
4600 >>> sc.expi(complex(-1, -0.0))
4601 (-0.21938393439552062-0j)
4603 """)
4605add_newdoc('expit',
4606 """
4607 expit(x, out=None)
4609 Expit (a.k.a. logistic sigmoid) ufunc for ndarrays.
4611 The expit function, also known as the logistic sigmoid function, is
4612 defined as ``expit(x) = 1/(1+exp(-x))``. It is the inverse of the
4613 logit function.
4615 Parameters
4616 ----------
4617 x : ndarray
4618 The ndarray to apply expit to element-wise.
4619 out : ndarray, optional
4620 Optional output array for the function values
4622 Returns
4623 -------
4624 scalar or ndarray
4625 An ndarray of the same shape as x. Its entries
4626 are `expit` of the corresponding entry of x.
4628 See Also
4629 --------
4630 logit
4632 Notes
4633 -----
4634 As a ufunc expit takes a number of optional
4635 keyword arguments. For more information
4636 see `ufuncs <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`_
4638 .. versionadded:: 0.10.0
4640 Examples
4641 --------
4642 >>> import numpy as np
4643 >>> from scipy.special import expit, logit
4645 >>> expit([-np.inf, -1.5, 0, 1.5, np.inf])
4646 array([ 0. , 0.18242552, 0.5 , 0.81757448, 1. ])
4648 `logit` is the inverse of `expit`:
4650 >>> logit(expit([-2.5, 0, 3.1, 5.0]))
4651 array([-2.5, 0. , 3.1, 5. ])
4653 Plot expit(x) for x in [-6, 6]:
4655 >>> import matplotlib.pyplot as plt
4656 >>> x = np.linspace(-6, 6, 121)
4657 >>> y = expit(x)
4658 >>> plt.plot(x, y)
4659 >>> plt.grid()
4660 >>> plt.xlim(-6, 6)
4661 >>> plt.xlabel('x')
4662 >>> plt.title('expit(x)')
4663 >>> plt.show()
4665 """)
4667add_newdoc("expm1",
4668 """
4669 expm1(x, out=None)
4671 Compute ``exp(x) - 1``.
4673 When `x` is near zero, ``exp(x)`` is near 1, so the numerical calculation
4674 of ``exp(x) - 1`` can suffer from catastrophic loss of precision.
4675 ``expm1(x)`` is implemented to avoid the loss of precision that occurs when
4676 `x` is near zero.
4678 Parameters
4679 ----------
4680 x : array_like
4681 `x` must contain real numbers.
4682 out : ndarray, optional
4683 Optional output array for the function values
4685 Returns
4686 -------
4687 scalar or ndarray
4688 ``exp(x) - 1`` computed element-wise.
4690 Examples
4691 --------
4692 >>> import numpy as np
4693 >>> from scipy.special import expm1
4695 >>> expm1(1.0)
4696 1.7182818284590451
4697 >>> expm1([-0.2, -0.1, 0, 0.1, 0.2])
4698 array([-0.18126925, -0.09516258, 0. , 0.10517092, 0.22140276])
4700 The exact value of ``exp(7.5e-13) - 1`` is::
4702 7.5000000000028125000000007031250000001318...*10**-13.
4704 Here is what ``expm1(7.5e-13)`` gives:
4706 >>> expm1(7.5e-13)
4707 7.5000000000028135e-13
4709 Compare that to ``exp(7.5e-13) - 1``, where the subtraction results in
4710 a "catastrophic" loss of precision:
4712 >>> np.exp(7.5e-13) - 1
4713 7.5006667543675576e-13
4715 """)
4717add_newdoc("expn",
4718 r"""
4719 expn(n, x, out=None)
4721 Generalized exponential integral En.
4723 For integer :math:`n \geq 0` and real :math:`x \geq 0` the
4724 generalized exponential integral is defined as [dlmf]_
4726 .. math::
4728 E_n(x) = x^{n - 1} \int_x^\infty \frac{e^{-t}}{t^n} dt.
4730 Parameters
4731 ----------
4732 n : array_like
4733 Non-negative integers
4734 x : array_like
4735 Real argument
4736 out : ndarray, optional
4737 Optional output array for the function results
4739 Returns
4740 -------
4741 scalar or ndarray
4742 Values of the generalized exponential integral
4744 See Also
4745 --------
4746 exp1 : special case of :math:`E_n` for :math:`n = 1`
4747 expi : related to :math:`E_n` when :math:`n = 1`
4749 References
4750 ----------
4751 .. [dlmf] Digital Library of Mathematical Functions, 8.19.2
4752 https://dlmf.nist.gov/8.19#E2
4754 Examples
4755 --------
4756 >>> import numpy as np
4757 >>> import scipy.special as sc
4759 Its domain is nonnegative n and x.
4761 >>> sc.expn(-1, 1.0), sc.expn(1, -1.0)
4762 (nan, nan)
4764 It has a pole at ``x = 0`` for ``n = 1, 2``; for larger ``n`` it
4765 is equal to ``1 / (n - 1)``.
4767 >>> sc.expn([0, 1, 2, 3, 4], 0)
4768 array([ inf, inf, 1. , 0.5 , 0.33333333])
4770 For n equal to 0 it reduces to ``exp(-x) / x``.
4772 >>> x = np.array([1, 2, 3, 4])
4773 >>> sc.expn(0, x)
4774 array([0.36787944, 0.06766764, 0.01659569, 0.00457891])
4775 >>> np.exp(-x) / x
4776 array([0.36787944, 0.06766764, 0.01659569, 0.00457891])
4778 For n equal to 1 it reduces to `exp1`.
4780 >>> sc.expn(1, x)
4781 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4782 >>> sc.exp1(x)
4783 array([0.21938393, 0.04890051, 0.01304838, 0.00377935])
4785 """)
4787add_newdoc("exprel",
4788 r"""
4789 exprel(x, out=None)
4791 Relative error exponential, ``(exp(x) - 1)/x``.
4793 When `x` is near zero, ``exp(x)`` is near 1, so the numerical calculation
4794 of ``exp(x) - 1`` can suffer from catastrophic loss of precision.
4795 ``exprel(x)`` is implemented to avoid the loss of precision that occurs when
4796 `x` is near zero.
4798 Parameters
4799 ----------
4800 x : ndarray
4801 Input array. `x` must contain real numbers.
4802 out : ndarray, optional
4803 Optional output array for the function values
4805 Returns
4806 -------
4807 scalar or ndarray
4808 ``(exp(x) - 1)/x``, computed element-wise.
4810 See Also
4811 --------
4812 expm1
4814 Notes
4815 -----
4816 .. versionadded:: 0.17.0
4818 Examples
4819 --------
4820 >>> import numpy as np
4821 >>> from scipy.special import exprel
4823 >>> exprel(0.01)
4824 1.0050167084168056
4825 >>> exprel([-0.25, -0.1, 0, 0.1, 0.25])
4826 array([ 0.88479687, 0.95162582, 1. , 1.05170918, 1.13610167])
4828 Compare ``exprel(5e-9)`` to the naive calculation. The exact value
4829 is ``1.00000000250000000416...``.
4831 >>> exprel(5e-9)
4832 1.0000000025
4834 >>> (np.exp(5e-9) - 1)/5e-9
4835 0.99999999392252903
4836 """)
4838add_newdoc("fdtr",
4839 r"""
4840 fdtr(dfn, dfd, x, out=None)
4842 F cumulative distribution function.
4844 Returns the value of the cumulative distribution function of the
4845 F-distribution, also known as Snedecor's F-distribution or the
4846 Fisher-Snedecor distribution.
4848 The F-distribution with parameters :math:`d_n` and :math:`d_d` is the
4849 distribution of the random variable,
4851 .. math::
4852 X = \frac{U_n/d_n}{U_d/d_d},
4854 where :math:`U_n` and :math:`U_d` are random variables distributed
4855 :math:`\chi^2`, with :math:`d_n` and :math:`d_d` degrees of freedom,
4856 respectively.
4858 Parameters
4859 ----------
4860 dfn : array_like
4861 First parameter (positive float).
4862 dfd : array_like
4863 Second parameter (positive float).
4864 x : array_like
4865 Argument (nonnegative float).
4866 out : ndarray, optional
4867 Optional output array for the function values
4869 Returns
4870 -------
4871 y : scalar or ndarray
4872 The CDF of the F-distribution with parameters `dfn` and `dfd` at `x`.
4874 See Also
4875 --------
4876 fdtrc : F distribution survival function
4877 fdtri : F distribution inverse cumulative distribution
4878 scipy.stats.f : F distribution
4880 Notes
4881 -----
4882 The regularized incomplete beta function is used, according to the
4883 formula,
4885 .. math::
4886 F(d_n, d_d; x) = I_{xd_n/(d_d + xd_n)}(d_n/2, d_d/2).
4888 Wrapper for the Cephes [1]_ routine `fdtr`. The F distribution is also
4889 available as `scipy.stats.f`. Calling `fdtr` directly can improve
4890 performance compared to the ``cdf`` method of `scipy.stats.f` (see last
4891 example below).
4893 References
4894 ----------
4895 .. [1] Cephes Mathematical Functions Library,
4896 http://www.netlib.org/cephes/
4898 Examples
4899 --------
4900 Calculate the function for ``dfn=1`` and ``dfd=2`` at ``x=1``.
4902 >>> import numpy as np
4903 >>> from scipy.special import fdtr
4904 >>> fdtr(1, 2, 1)
4905 0.5773502691896258
4907 Calculate the function at several points by providing a NumPy array for
4908 `x`.
4910 >>> x = np.array([0.5, 2., 3.])
4911 >>> fdtr(1, 2, x)
4912 array([0.4472136 , 0.70710678, 0.77459667])
4914 Plot the function for several parameter sets.
4916 >>> import matplotlib.pyplot as plt
4917 >>> dfn_parameters = [1, 5, 10, 50]
4918 >>> dfd_parameters = [1, 1, 2, 3]
4919 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
4920 >>> parameters_list = list(zip(dfn_parameters, dfd_parameters,
4921 ... linestyles))
4922 >>> x = np.linspace(0, 30, 1000)
4923 >>> fig, ax = plt.subplots()
4924 >>> for parameter_set in parameters_list:
4925 ... dfn, dfd, style = parameter_set
4926 ... fdtr_vals = fdtr(dfn, dfd, x)
4927 ... ax.plot(x, fdtr_vals, label=rf"$d_n={dfn},\, d_d={dfd}$",
4928 ... ls=style)
4929 >>> ax.legend()
4930 >>> ax.set_xlabel("$x$")
4931 >>> ax.set_title("F distribution cumulative distribution function")
4932 >>> plt.show()
4934 The F distribution is also available as `scipy.stats.f`. Using `fdtr`
4935 directly can be much faster than calling the ``cdf`` method of
4936 `scipy.stats.f`, especially for small arrays or individual values.
4937 To get the same results one must use the following parametrization:
4938 ``stats.f(dfn, dfd).cdf(x)=fdtr(dfn, dfd, x)``.
4940 >>> from scipy.stats import f
4941 >>> dfn, dfd = 1, 2
4942 >>> x = 1
4943 >>> fdtr_res = fdtr(dfn, dfd, x) # this will often be faster than below
4944 >>> f_dist_res = f(dfn, dfd).cdf(x)
4945 >>> fdtr_res == f_dist_res # test that results are equal
4946 True
4947 """)
4949add_newdoc("fdtrc",
4950 r"""
4951 fdtrc(dfn, dfd, x, out=None)
4953 F survival function.
4955 Returns the complemented F-distribution function (the integral of the
4956 density from `x` to infinity).
4958 Parameters
4959 ----------
4960 dfn : array_like
4961 First parameter (positive float).
4962 dfd : array_like
4963 Second parameter (positive float).
4964 x : array_like
4965 Argument (nonnegative float).
4966 out : ndarray, optional
4967 Optional output array for the function values
4969 Returns
4970 -------
4971 y : scalar or ndarray
4972 The complemented F-distribution function with parameters `dfn` and
4973 `dfd` at `x`.
4975 See Also
4976 --------
4977 fdtr : F distribution cumulative distribution function
4978 fdtri : F distribution inverse cumulative distribution function
4979 scipy.stats.f : F distribution
4981 Notes
4982 -----
4983 The regularized incomplete beta function is used, according to the
4984 formula,
4986 .. math::
4987 F(d_n, d_d; x) = I_{d_d/(d_d + xd_n)}(d_d/2, d_n/2).
4989 Wrapper for the Cephes [1]_ routine `fdtrc`. The F distribution is also
4990 available as `scipy.stats.f`. Calling `fdtrc` directly can improve
4991 performance compared to the ``sf`` method of `scipy.stats.f` (see last
4992 example below).
4994 References
4995 ----------
4996 .. [1] Cephes Mathematical Functions Library,
4997 http://www.netlib.org/cephes/
4999 Examples
5000 --------
5001 Calculate the function for ``dfn=1`` and ``dfd=2`` at ``x=1``.
5003 >>> import numpy as np
5004 >>> from scipy.special import fdtrc
5005 >>> fdtrc(1, 2, 1)
5006 0.42264973081037427
5008 Calculate the function at several points by providing a NumPy array for
5009 `x`.
5011 >>> x = np.array([0.5, 2., 3.])
5012 >>> fdtrc(1, 2, x)
5013 array([0.5527864 , 0.29289322, 0.22540333])
5015 Plot the function for several parameter sets.
5017 >>> import matplotlib.pyplot as plt
5018 >>> dfn_parameters = [1, 5, 10, 50]
5019 >>> dfd_parameters = [1, 1, 2, 3]
5020 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5021 >>> parameters_list = list(zip(dfn_parameters, dfd_parameters,
5022 ... linestyles))
5023 >>> x = np.linspace(0, 30, 1000)
5024 >>> fig, ax = plt.subplots()
5025 >>> for parameter_set in parameters_list:
5026 ... dfn, dfd, style = parameter_set
5027 ... fdtrc_vals = fdtrc(dfn, dfd, x)
5028 ... ax.plot(x, fdtrc_vals, label=rf"$d_n={dfn},\, d_d={dfd}$",
5029 ... ls=style)
5030 >>> ax.legend()
5031 >>> ax.set_xlabel("$x$")
5032 >>> ax.set_title("F distribution survival function")
5033 >>> plt.show()
5035 The F distribution is also available as `scipy.stats.f`. Using `fdtrc`
5036 directly can be much faster than calling the ``sf`` method of
5037 `scipy.stats.f`, especially for small arrays or individual values.
5038 To get the same results one must use the following parametrization:
5039 ``stats.f(dfn, dfd).sf(x)=fdtrc(dfn, dfd, x)``.
5041 >>> from scipy.stats import f
5042 >>> dfn, dfd = 1, 2
5043 >>> x = 1
5044 >>> fdtrc_res = fdtrc(dfn, dfd, x) # this will often be faster than below
5045 >>> f_dist_res = f(dfn, dfd).sf(x)
5046 >>> f_dist_res == fdtrc_res # test that results are equal
5047 True
5048 """)
5050add_newdoc("fdtri",
5051 r"""
5052 fdtri(dfn, dfd, p, out=None)
5054 The `p`-th quantile of the F-distribution.
5056 This function is the inverse of the F-distribution CDF, `fdtr`, returning
5057 the `x` such that `fdtr(dfn, dfd, x) = p`.
5059 Parameters
5060 ----------
5061 dfn : array_like
5062 First parameter (positive float).
5063 dfd : array_like
5064 Second parameter (positive float).
5065 p : array_like
5066 Cumulative probability, in [0, 1].
5067 out : ndarray, optional
5068 Optional output array for the function values
5070 Returns
5071 -------
5072 x : scalar or ndarray
5073 The quantile corresponding to `p`.
5075 See Also
5076 --------
5077 fdtr : F distribution cumulative distribution function
5078 fdtrc : F distribution survival function
5079 scipy.stats.f : F distribution
5081 Notes
5082 -----
5083 The computation is carried out using the relation to the inverse
5084 regularized beta function, :math:`I^{-1}_x(a, b)`. Let
5085 :math:`z = I^{-1}_p(d_d/2, d_n/2).` Then,
5087 .. math::
5088 x = \frac{d_d (1 - z)}{d_n z}.
5090 If `p` is such that :math:`x < 0.5`, the following relation is used
5091 instead for improved stability: let
5092 :math:`z' = I^{-1}_{1 - p}(d_n/2, d_d/2).` Then,
5094 .. math::
5095 x = \frac{d_d z'}{d_n (1 - z')}.
5097 Wrapper for the Cephes [1]_ routine `fdtri`.
5099 The F distribution is also available as `scipy.stats.f`. Calling
5100 `fdtri` directly can improve performance compared to the ``ppf``
5101 method of `scipy.stats.f` (see last example below).
5103 References
5104 ----------
5105 .. [1] Cephes Mathematical Functions Library,
5106 http://www.netlib.org/cephes/
5108 Examples
5109 --------
5110 `fdtri` represents the inverse of the F distribution CDF which is
5111 available as `fdtr`. Here, we calculate the CDF for ``df1=1``, ``df2=2``
5112 at ``x=3``. `fdtri` then returns ``3`` given the same values for `df1`,
5113 `df2` and the computed CDF value.
5115 >>> import numpy as np
5116 >>> from scipy.special import fdtri, fdtr
5117 >>> df1, df2 = 1, 2
5118 >>> x = 3
5119 >>> cdf_value = fdtr(df1, df2, x)
5120 >>> fdtri(df1, df2, cdf_value)
5121 3.000000000000006
5123 Calculate the function at several points by providing a NumPy array for
5124 `x`.
5126 >>> x = np.array([0.1, 0.4, 0.7])
5127 >>> fdtri(1, 2, x)
5128 array([0.02020202, 0.38095238, 1.92156863])
5130 Plot the function for several parameter sets.
5132 >>> import matplotlib.pyplot as plt
5133 >>> dfn_parameters = [50, 10, 1, 50]
5134 >>> dfd_parameters = [0.5, 1, 1, 5]
5135 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5136 >>> parameters_list = list(zip(dfn_parameters, dfd_parameters,
5137 ... linestyles))
5138 >>> x = np.linspace(0, 1, 1000)
5139 >>> fig, ax = plt.subplots()
5140 >>> for parameter_set in parameters_list:
5141 ... dfn, dfd, style = parameter_set
5142 ... fdtri_vals = fdtri(dfn, dfd, x)
5143 ... ax.plot(x, fdtri_vals, label=rf"$d_n={dfn},\, d_d={dfd}$",
5144 ... ls=style)
5145 >>> ax.legend()
5146 >>> ax.set_xlabel("$x$")
5147 >>> title = "F distribution inverse cumulative distribution function"
5148 >>> ax.set_title(title)
5149 >>> ax.set_ylim(0, 30)
5150 >>> plt.show()
5152 The F distribution is also available as `scipy.stats.f`. Using `fdtri`
5153 directly can be much faster than calling the ``ppf`` method of
5154 `scipy.stats.f`, especially for small arrays or individual values.
5155 To get the same results one must use the following parametrization:
5156 ``stats.f(dfn, dfd).ppf(x)=fdtri(dfn, dfd, x)``.
5158 >>> from scipy.stats import f
5159 >>> dfn, dfd = 1, 2
5160 >>> x = 0.7
5161 >>> fdtri_res = fdtri(dfn, dfd, x) # this will often be faster than below
5162 >>> f_dist_res = f(dfn, dfd).ppf(x)
5163 >>> f_dist_res == fdtri_res # test that results are equal
5164 True
5165 """)
5167add_newdoc("fdtridfd",
5168 """
5169 fdtridfd(dfn, p, x, out=None)
5171 Inverse to `fdtr` vs dfd
5173 Finds the F density argument dfd such that ``fdtr(dfn, dfd, x) == p``.
5175 Parameters
5176 ----------
5177 dfn : array_like
5178 First parameter (positive float).
5179 p : array_like
5180 Cumulative probability, in [0, 1].
5181 x : array_like
5182 Argument (nonnegative float).
5183 out : ndarray, optional
5184 Optional output array for the function values
5186 Returns
5187 -------
5188 dfd : scalar or ndarray
5189 `dfd` such that ``fdtr(dfn, dfd, x) == p``.
5191 See Also
5192 --------
5193 fdtr, fdtrc, fdtri
5195 """)
5197'''
5198commented out as fdtridfn seems to have bugs and is not in functions.json
5199see: https://github.com/scipy/scipy/pull/15622#discussion_r811440983
5201add_newdoc(
5202 "fdtridfn",
5203 """
5204 fdtridfn(p, dfd, x, out=None)
5206 Inverse to `fdtr` vs dfn
5208 finds the F density argument dfn such that ``fdtr(dfn, dfd, x) == p``.
5211 Parameters
5212 ----------
5213 p : array_like
5214 Cumulative probability, in [0, 1].
5215 dfd : array_like
5216 Second parameter (positive float).
5217 x : array_like
5218 Argument (nonnegative float).
5219 out : ndarray, optional
5220 Optional output array for the function values
5222 Returns
5223 -------
5224 dfn : scalar or ndarray
5225 `dfn` such that ``fdtr(dfn, dfd, x) == p``.
5227 See Also
5228 --------
5229 fdtr, fdtrc, fdtri, fdtridfd
5232 """)
5233'''
5235add_newdoc("fresnel",
5236 r"""
5237 fresnel(z, out=None)
5239 Fresnel integrals.
5241 The Fresnel integrals are defined as
5243 .. math::
5245 S(z) &= \int_0^z \sin(\pi t^2 /2) dt \\
5246 C(z) &= \int_0^z \cos(\pi t^2 /2) dt.
5248 See [dlmf]_ for details.
5250 Parameters
5251 ----------
5252 z : array_like
5253 Real or complex valued argument
5254 out : 2-tuple of ndarrays, optional
5255 Optional output arrays for the function results
5257 Returns
5258 -------
5259 S, C : 2-tuple of scalar or ndarray
5260 Values of the Fresnel integrals
5262 See Also
5263 --------
5264 fresnel_zeros : zeros of the Fresnel integrals
5266 References
5267 ----------
5268 .. [dlmf] NIST Digital Library of Mathematical Functions
5269 https://dlmf.nist.gov/7.2#iii
5271 Examples
5272 --------
5273 >>> import numpy as np
5274 >>> import scipy.special as sc
5276 As z goes to infinity along the real axis, S and C converge to 0.5.
5278 >>> S, C = sc.fresnel([0.1, 1, 10, 100, np.inf])
5279 >>> S
5280 array([0.00052359, 0.43825915, 0.46816998, 0.4968169 , 0.5 ])
5281 >>> C
5282 array([0.09999753, 0.7798934 , 0.49989869, 0.4999999 , 0.5 ])
5284 They are related to the error function `erf`.
5286 >>> z = np.array([1, 2, 3, 4])
5287 >>> zeta = 0.5 * np.sqrt(np.pi) * (1 - 1j) * z
5288 >>> S, C = sc.fresnel(z)
5289 >>> C + 1j*S
5290 array([0.7798934 +0.43825915j, 0.48825341+0.34341568j,
5291 0.60572079+0.496313j , 0.49842603+0.42051575j])
5292 >>> 0.5 * (1 + 1j) * sc.erf(zeta)
5293 array([0.7798934 +0.43825915j, 0.48825341+0.34341568j,
5294 0.60572079+0.496313j , 0.49842603+0.42051575j])
5296 """)
5298add_newdoc("gamma",
5299 r"""
5300 gamma(z, out=None)
5302 gamma function.
5304 The gamma function is defined as
5306 .. math::
5308 \Gamma(z) = \int_0^\infty t^{z-1} e^{-t} dt
5310 for :math:`\Re(z) > 0` and is extended to the rest of the complex
5311 plane by analytic continuation. See [dlmf]_ for more details.
5313 Parameters
5314 ----------
5315 z : array_like
5316 Real or complex valued argument
5317 out : ndarray, optional
5318 Optional output array for the function values
5320 Returns
5321 -------
5322 scalar or ndarray
5323 Values of the gamma function
5325 Notes
5326 -----
5327 The gamma function is often referred to as the generalized
5328 factorial since :math:`\Gamma(n + 1) = n!` for natural numbers
5329 :math:`n`. More generally it satisfies the recurrence relation
5330 :math:`\Gamma(z + 1) = z \cdot \Gamma(z)` for complex :math:`z`,
5331 which, combined with the fact that :math:`\Gamma(1) = 1`, implies
5332 the above identity for :math:`z = n`.
5334 References
5335 ----------
5336 .. [dlmf] NIST Digital Library of Mathematical Functions
5337 https://dlmf.nist.gov/5.2#E1
5339 Examples
5340 --------
5341 >>> import numpy as np
5342 >>> from scipy.special import gamma, factorial
5344 >>> gamma([0, 0.5, 1, 5])
5345 array([ inf, 1.77245385, 1. , 24. ])
5347 >>> z = 2.5 + 1j
5348 >>> gamma(z)
5349 (0.77476210455108352+0.70763120437959293j)
5350 >>> gamma(z+1), z*gamma(z) # Recurrence property
5351 ((1.2292740569981171+2.5438401155000685j),
5352 (1.2292740569981158+2.5438401155000658j))
5354 >>> gamma(0.5)**2 # gamma(0.5) = sqrt(pi)
5355 3.1415926535897927
5357 Plot gamma(x) for real x
5359 >>> x = np.linspace(-3.5, 5.5, 2251)
5360 >>> y = gamma(x)
5362 >>> import matplotlib.pyplot as plt
5363 >>> plt.plot(x, y, 'b', alpha=0.6, label='gamma(x)')
5364 >>> k = np.arange(1, 7)
5365 >>> plt.plot(k, factorial(k-1), 'k*', alpha=0.6,
5366 ... label='(x-1)!, x = 1, 2, ...')
5367 >>> plt.xlim(-3.5, 5.5)
5368 >>> plt.ylim(-10, 25)
5369 >>> plt.grid()
5370 >>> plt.xlabel('x')
5371 >>> plt.legend(loc='lower right')
5372 >>> plt.show()
5374 """)
5376add_newdoc("gammainc",
5377 r"""
5378 gammainc(a, x, out=None)
5380 Regularized lower incomplete gamma function.
5382 It is defined as
5384 .. math::
5386 P(a, x) = \frac{1}{\Gamma(a)} \int_0^x t^{a - 1}e^{-t} dt
5388 for :math:`a > 0` and :math:`x \geq 0`. See [dlmf]_ for details.
5390 Parameters
5391 ----------
5392 a : array_like
5393 Positive parameter
5394 x : array_like
5395 Nonnegative argument
5396 out : ndarray, optional
5397 Optional output array for the function values
5399 Returns
5400 -------
5401 scalar or ndarray
5402 Values of the lower incomplete gamma function
5404 Notes
5405 -----
5406 The function satisfies the relation ``gammainc(a, x) +
5407 gammaincc(a, x) = 1`` where `gammaincc` is the regularized upper
5408 incomplete gamma function.
5410 The implementation largely follows that of [boost]_.
5412 See also
5413 --------
5414 gammaincc : regularized upper incomplete gamma function
5415 gammaincinv : inverse of the regularized lower incomplete gamma function
5416 gammainccinv : inverse of the regularized upper incomplete gamma function
5418 References
5419 ----------
5420 .. [dlmf] NIST Digital Library of Mathematical functions
5421 https://dlmf.nist.gov/8.2#E4
5422 .. [boost] Maddock et. al., "Incomplete Gamma Functions",
5423 https://www.boost.org/doc/libs/1_61_0/libs/math/doc/html/math_toolkit/sf_gamma/igamma.html
5425 Examples
5426 --------
5427 >>> import scipy.special as sc
5429 It is the CDF of the gamma distribution, so it starts at 0 and
5430 monotonically increases to 1.
5432 >>> sc.gammainc(0.5, [0, 1, 10, 100])
5433 array([0. , 0.84270079, 0.99999226, 1. ])
5435 It is equal to one minus the upper incomplete gamma function.
5437 >>> a, x = 0.5, 0.4
5438 >>> sc.gammainc(a, x)
5439 0.6289066304773024
5440 >>> 1 - sc.gammaincc(a, x)
5441 0.6289066304773024
5443 """)
5445add_newdoc("gammaincc",
5446 r"""
5447 gammaincc(a, x, out=None)
5449 Regularized upper incomplete gamma function.
5451 It is defined as
5453 .. math::
5455 Q(a, x) = \frac{1}{\Gamma(a)} \int_x^\infty t^{a - 1}e^{-t} dt
5457 for :math:`a > 0` and :math:`x \geq 0`. See [dlmf]_ for details.
5459 Parameters
5460 ----------
5461 a : array_like
5462 Positive parameter
5463 x : array_like
5464 Nonnegative argument
5465 out : ndarray, optional
5466 Optional output array for the function values
5468 Returns
5469 -------
5470 scalar or ndarray
5471 Values of the upper incomplete gamma function
5473 Notes
5474 -----
5475 The function satisfies the relation ``gammainc(a, x) +
5476 gammaincc(a, x) = 1`` where `gammainc` is the regularized lower
5477 incomplete gamma function.
5479 The implementation largely follows that of [boost]_.
5481 See also
5482 --------
5483 gammainc : regularized lower incomplete gamma function
5484 gammaincinv : inverse of the regularized lower incomplete gamma function
5485 gammainccinv : inverse of the regularized upper incomplete gamma function
5487 References
5488 ----------
5489 .. [dlmf] NIST Digital Library of Mathematical functions
5490 https://dlmf.nist.gov/8.2#E4
5491 .. [boost] Maddock et. al., "Incomplete Gamma Functions",
5492 https://www.boost.org/doc/libs/1_61_0/libs/math/doc/html/math_toolkit/sf_gamma/igamma.html
5494 Examples
5495 --------
5496 >>> import scipy.special as sc
5498 It is the survival function of the gamma distribution, so it
5499 starts at 1 and monotonically decreases to 0.
5501 >>> sc.gammaincc(0.5, [0, 1, 10, 100, 1000])
5502 array([1.00000000e+00, 1.57299207e-01, 7.74421643e-06, 2.08848758e-45,
5503 0.00000000e+00])
5505 It is equal to one minus the lower incomplete gamma function.
5507 >>> a, x = 0.5, 0.4
5508 >>> sc.gammaincc(a, x)
5509 0.37109336952269756
5510 >>> 1 - sc.gammainc(a, x)
5511 0.37109336952269756
5513 """)
5515add_newdoc("gammainccinv",
5516 """
5517 gammainccinv(a, y, out=None)
5519 Inverse of the regularized upper incomplete gamma function.
5521 Given an input :math:`y` between 0 and 1, returns :math:`x` such
5522 that :math:`y = Q(a, x)`. Here :math:`Q` is the regularized upper
5523 incomplete gamma function; see `gammaincc`. This is well-defined
5524 because the upper incomplete gamma function is monotonic as can
5525 be seen from its definition in [dlmf]_.
5527 Parameters
5528 ----------
5529 a : array_like
5530 Positive parameter
5531 y : array_like
5532 Argument between 0 and 1, inclusive
5533 out : ndarray, optional
5534 Optional output array for the function values
5536 Returns
5537 -------
5538 scalar or ndarray
5539 Values of the inverse of the upper incomplete gamma function
5541 See Also
5542 --------
5543 gammaincc : regularized upper incomplete gamma function
5544 gammainc : regularized lower incomplete gamma function
5545 gammaincinv : inverse of the regularized lower incomplete gamma function
5547 References
5548 ----------
5549 .. [dlmf] NIST Digital Library of Mathematical Functions
5550 https://dlmf.nist.gov/8.2#E4
5552 Examples
5553 --------
5554 >>> import scipy.special as sc
5556 It starts at infinity and monotonically decreases to 0.
5558 >>> sc.gammainccinv(0.5, [0, 0.1, 0.5, 1])
5559 array([ inf, 1.35277173, 0.22746821, 0. ])
5561 It inverts the upper incomplete gamma function.
5563 >>> a, x = 0.5, [0, 0.1, 0.5, 1]
5564 >>> sc.gammaincc(a, sc.gammainccinv(a, x))
5565 array([0. , 0.1, 0.5, 1. ])
5567 >>> a, x = 0.5, [0, 10, 50]
5568 >>> sc.gammainccinv(a, sc.gammaincc(a, x))
5569 array([ 0., 10., 50.])
5571 """)
5573add_newdoc("gammaincinv",
5574 """
5575 gammaincinv(a, y, out=None)
5577 Inverse to the regularized lower incomplete gamma function.
5579 Given an input :math:`y` between 0 and 1, returns :math:`x` such
5580 that :math:`y = P(a, x)`. Here :math:`P` is the regularized lower
5581 incomplete gamma function; see `gammainc`. This is well-defined
5582 because the lower incomplete gamma function is monotonic as can be
5583 seen from its definition in [dlmf]_.
5585 Parameters
5586 ----------
5587 a : array_like
5588 Positive parameter
5589 y : array_like
5590 Parameter between 0 and 1, inclusive
5591 out : ndarray, optional
5592 Optional output array for the function values
5594 Returns
5595 -------
5596 scalar or ndarray
5597 Values of the inverse of the lower incomplete gamma function
5599 See Also
5600 --------
5601 gammainc : regularized lower incomplete gamma function
5602 gammaincc : regularized upper incomplete gamma function
5603 gammainccinv : inverse of the regularized upper incomplete gamma function
5605 References
5606 ----------
5607 .. [dlmf] NIST Digital Library of Mathematical Functions
5608 https://dlmf.nist.gov/8.2#E4
5610 Examples
5611 --------
5612 >>> import scipy.special as sc
5614 It starts at 0 and monotonically increases to infinity.
5616 >>> sc.gammaincinv(0.5, [0, 0.1 ,0.5, 1])
5617 array([0. , 0.00789539, 0.22746821, inf])
5619 It inverts the lower incomplete gamma function.
5621 >>> a, x = 0.5, [0, 0.1, 0.5, 1]
5622 >>> sc.gammainc(a, sc.gammaincinv(a, x))
5623 array([0. , 0.1, 0.5, 1. ])
5625 >>> a, x = 0.5, [0, 10, 25]
5626 >>> sc.gammaincinv(a, sc.gammainc(a, x))
5627 array([ 0. , 10. , 25.00001465])
5629 """)
5631add_newdoc("gammaln",
5632 r"""
5633 gammaln(x, out=None)
5635 Logarithm of the absolute value of the gamma function.
5637 Defined as
5639 .. math::
5641 \ln(\lvert\Gamma(x)\rvert)
5643 where :math:`\Gamma` is the gamma function. For more details on
5644 the gamma function, see [dlmf]_.
5646 Parameters
5647 ----------
5648 x : array_like
5649 Real argument
5650 out : ndarray, optional
5651 Optional output array for the function results
5653 Returns
5654 -------
5655 scalar or ndarray
5656 Values of the log of the absolute value of gamma
5658 See Also
5659 --------
5660 gammasgn : sign of the gamma function
5661 loggamma : principal branch of the logarithm of the gamma function
5663 Notes
5664 -----
5665 It is the same function as the Python standard library function
5666 :func:`math.lgamma`.
5668 When used in conjunction with `gammasgn`, this function is useful
5669 for working in logspace on the real axis without having to deal
5670 with complex numbers via the relation ``exp(gammaln(x)) =
5671 gammasgn(x) * gamma(x)``.
5673 For complex-valued log-gamma, use `loggamma` instead of `gammaln`.
5675 References
5676 ----------
5677 .. [dlmf] NIST Digital Library of Mathematical Functions
5678 https://dlmf.nist.gov/5
5680 Examples
5681 --------
5682 >>> import numpy as np
5683 >>> import scipy.special as sc
5685 It has two positive zeros.
5687 >>> sc.gammaln([1, 2])
5688 array([0., 0.])
5690 It has poles at nonpositive integers.
5692 >>> sc.gammaln([0, -1, -2, -3, -4])
5693 array([inf, inf, inf, inf, inf])
5695 It asymptotically approaches ``x * log(x)`` (Stirling's formula).
5697 >>> x = np.array([1e10, 1e20, 1e40, 1e80])
5698 >>> sc.gammaln(x)
5699 array([2.20258509e+11, 4.50517019e+21, 9.11034037e+41, 1.83206807e+82])
5700 >>> x * np.log(x)
5701 array([2.30258509e+11, 4.60517019e+21, 9.21034037e+41, 1.84206807e+82])
5703 """)
5705add_newdoc("gammasgn",
5706 r"""
5707 gammasgn(x, out=None)
5709 Sign of the gamma function.
5711 It is defined as
5713 .. math::
5715 \text{gammasgn}(x) =
5716 \begin{cases}
5717 +1 & \Gamma(x) > 0 \\
5718 -1 & \Gamma(x) < 0
5719 \end{cases}
5721 where :math:`\Gamma` is the gamma function; see `gamma`. This
5722 definition is complete since the gamma function is never zero;
5723 see the discussion after [dlmf]_.
5725 Parameters
5726 ----------
5727 x : array_like
5728 Real argument
5729 out : ndarray, optional
5730 Optional output array for the function values
5732 Returns
5733 -------
5734 scalar or ndarray
5735 Sign of the gamma function
5737 Notes
5738 -----
5739 The gamma function can be computed as ``gammasgn(x) *
5740 np.exp(gammaln(x))``.
5742 See Also
5743 --------
5744 gamma : the gamma function
5745 gammaln : log of the absolute value of the gamma function
5746 loggamma : analytic continuation of the log of the gamma function
5748 References
5749 ----------
5750 .. [dlmf] NIST Digital Library of Mathematical Functions
5751 https://dlmf.nist.gov/5.2#E1
5753 Examples
5754 --------
5755 >>> import numpy as np
5756 >>> import scipy.special as sc
5758 It is 1 for `x > 0`.
5760 >>> sc.gammasgn([1, 2, 3, 4])
5761 array([1., 1., 1., 1.])
5763 It alternates between -1 and 1 for negative integers.
5765 >>> sc.gammasgn([-0.5, -1.5, -2.5, -3.5])
5766 array([-1., 1., -1., 1.])
5768 It can be used to compute the gamma function.
5770 >>> x = [1.5, 0.5, -0.5, -1.5]
5771 >>> sc.gammasgn(x) * np.exp(sc.gammaln(x))
5772 array([ 0.88622693, 1.77245385, -3.5449077 , 2.3632718 ])
5773 >>> sc.gamma(x)
5774 array([ 0.88622693, 1.77245385, -3.5449077 , 2.3632718 ])
5776 """)
5778add_newdoc("gdtr",
5779 r"""
5780 gdtr(a, b, x, out=None)
5782 Gamma distribution cumulative distribution function.
5784 Returns the integral from zero to `x` of the gamma probability density
5785 function,
5787 .. math::
5789 F = \int_0^x \frac{a^b}{\Gamma(b)} t^{b-1} e^{-at}\,dt,
5791 where :math:`\Gamma` is the gamma function.
5793 Parameters
5794 ----------
5795 a : array_like
5796 The rate parameter of the gamma distribution, sometimes denoted
5797 :math:`\beta` (float). It is also the reciprocal of the scale
5798 parameter :math:`\theta`.
5799 b : array_like
5800 The shape parameter of the gamma distribution, sometimes denoted
5801 :math:`\alpha` (float).
5802 x : array_like
5803 The quantile (upper limit of integration; float).
5804 out : ndarray, optional
5805 Optional output array for the function values
5807 See also
5808 --------
5809 gdtrc : 1 - CDF of the gamma distribution.
5810 scipy.stats.gamma: Gamma distribution
5812 Returns
5813 -------
5814 F : scalar or ndarray
5815 The CDF of the gamma distribution with parameters `a` and `b`
5816 evaluated at `x`.
5818 Notes
5819 -----
5820 The evaluation is carried out using the relation to the incomplete gamma
5821 integral (regularized gamma function).
5823 Wrapper for the Cephes [1]_ routine `gdtr`. Calling `gdtr` directly can
5824 improve performance compared to the ``cdf`` method of `scipy.stats.gamma`
5825 (see last example below).
5827 References
5828 ----------
5829 .. [1] Cephes Mathematical Functions Library,
5830 http://www.netlib.org/cephes/
5832 Examples
5833 --------
5834 Compute the function for ``a=1``, ``b=2`` at ``x=5``.
5836 >>> import numpy as np
5837 >>> from scipy.special import gdtr
5838 >>> import matplotlib.pyplot as plt
5839 >>> gdtr(1., 2., 5.)
5840 0.9595723180054873
5842 Compute the function for ``a=1`` and ``b=2`` at several points by
5843 providing a NumPy array for `x`.
5845 >>> xvalues = np.array([1., 2., 3., 4])
5846 >>> gdtr(1., 1., xvalues)
5847 array([0.63212056, 0.86466472, 0.95021293, 0.98168436])
5849 `gdtr` can evaluate different parameter sets by providing arrays with
5850 broadcasting compatible shapes for `a`, `b` and `x`. Here we compute the
5851 function for three different `a` at four positions `x` and ``b=3``,
5852 resulting in a 3x4 array.
5854 >>> a = np.array([[0.5], [1.5], [2.5]])
5855 >>> x = np.array([1., 2., 3., 4])
5856 >>> a.shape, x.shape
5857 ((3, 1), (4,))
5859 >>> gdtr(a, 3., x)
5860 array([[0.01438768, 0.0803014 , 0.19115317, 0.32332358],
5861 [0.19115317, 0.57680992, 0.82642193, 0.9380312 ],
5862 [0.45618688, 0.87534798, 0.97974328, 0.9972306 ]])
5864 Plot the function for four different parameter sets.
5866 >>> a_parameters = [0.3, 1, 2, 6]
5867 >>> b_parameters = [2, 10, 15, 20]
5868 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5869 >>> parameters_list = list(zip(a_parameters, b_parameters, linestyles))
5870 >>> x = np.linspace(0, 30, 1000)
5871 >>> fig, ax = plt.subplots()
5872 >>> for parameter_set in parameters_list:
5873 ... a, b, style = parameter_set
5874 ... gdtr_vals = gdtr(a, b, x)
5875 ... ax.plot(x, gdtr_vals, label=f"$a= {a},\, b={b}$", ls=style)
5876 >>> ax.legend()
5877 >>> ax.set_xlabel("$x$")
5878 >>> ax.set_title("Gamma distribution cumulative distribution function")
5879 >>> plt.show()
5881 The gamma distribution is also available as `scipy.stats.gamma`. Using
5882 `gdtr` directly can be much faster than calling the ``cdf`` method of
5883 `scipy.stats.gamma`, especially for small arrays or individual values.
5884 To get the same results one must use the following parametrization:
5885 ``stats.gamma(b, scale=1/a).cdf(x)=gdtr(a, b, x)``.
5887 >>> from scipy.stats import gamma
5888 >>> a = 2.
5889 >>> b = 3
5890 >>> x = 1.
5891 >>> gdtr_result = gdtr(a, b, x) # this will often be faster than below
5892 >>> gamma_dist_result = gamma(b, scale=1/a).cdf(x)
5893 >>> gdtr_result == gamma_dist_result # test that results are equal
5894 True
5895 """)
5897add_newdoc("gdtrc",
5898 r"""
5899 gdtrc(a, b, x, out=None)
5901 Gamma distribution survival function.
5903 Integral from `x` to infinity of the gamma probability density function,
5905 .. math::
5907 F = \int_x^\infty \frac{a^b}{\Gamma(b)} t^{b-1} e^{-at}\,dt,
5909 where :math:`\Gamma` is the gamma function.
5911 Parameters
5912 ----------
5913 a : array_like
5914 The rate parameter of the gamma distribution, sometimes denoted
5915 :math:`\beta` (float). It is also the reciprocal of the scale
5916 parameter :math:`\theta`.
5917 b : array_like
5918 The shape parameter of the gamma distribution, sometimes denoted
5919 :math:`\alpha` (float).
5920 x : array_like
5921 The quantile (lower limit of integration; float).
5922 out : ndarray, optional
5923 Optional output array for the function values
5925 Returns
5926 -------
5927 F : scalar or ndarray
5928 The survival function of the gamma distribution with parameters `a`
5929 and `b` evaluated at `x`.
5931 See Also
5932 --------
5933 gdtr: Gamma distribution cumulative distribution function
5934 scipy.stats.gamma: Gamma distribution
5935 gdtrix
5937 Notes
5938 -----
5939 The evaluation is carried out using the relation to the incomplete gamma
5940 integral (regularized gamma function).
5942 Wrapper for the Cephes [1]_ routine `gdtrc`. Calling `gdtrc` directly can
5943 improve performance compared to the ``sf`` method of `scipy.stats.gamma`
5944 (see last example below).
5946 References
5947 ----------
5948 .. [1] Cephes Mathematical Functions Library,
5949 http://www.netlib.org/cephes/
5951 Examples
5952 --------
5953 Compute the function for ``a=1`` and ``b=2`` at ``x=5``.
5955 >>> import numpy as np
5956 >>> from scipy.special import gdtrc
5957 >>> import matplotlib.pyplot as plt
5958 >>> gdtrc(1., 2., 5.)
5959 0.04042768199451279
5961 Compute the function for ``a=1``, ``b=2`` at several points by providing
5962 a NumPy array for `x`.
5964 >>> xvalues = np.array([1., 2., 3., 4])
5965 >>> gdtrc(1., 1., xvalues)
5966 array([0.36787944, 0.13533528, 0.04978707, 0.01831564])
5968 `gdtrc` can evaluate different parameter sets by providing arrays with
5969 broadcasting compatible shapes for `a`, `b` and `x`. Here we compute the
5970 function for three different `a` at four positions `x` and ``b=3``,
5971 resulting in a 3x4 array.
5973 >>> a = np.array([[0.5], [1.5], [2.5]])
5974 >>> x = np.array([1., 2., 3., 4])
5975 >>> a.shape, x.shape
5976 ((3, 1), (4,))
5978 >>> gdtrc(a, 3., x)
5979 array([[0.98561232, 0.9196986 , 0.80884683, 0.67667642],
5980 [0.80884683, 0.42319008, 0.17357807, 0.0619688 ],
5981 [0.54381312, 0.12465202, 0.02025672, 0.0027694 ]])
5983 Plot the function for four different parameter sets.
5985 >>> a_parameters = [0.3, 1, 2, 6]
5986 >>> b_parameters = [2, 10, 15, 20]
5987 >>> linestyles = ['solid', 'dashed', 'dotted', 'dashdot']
5988 >>> parameters_list = list(zip(a_parameters, b_parameters, linestyles))
5989 >>> x = np.linspace(0, 30, 1000)
5990 >>> fig, ax = plt.subplots()
5991 >>> for parameter_set in parameters_list:
5992 ... a, b, style = parameter_set
5993 ... gdtrc_vals = gdtrc(a, b, x)
5994 ... ax.plot(x, gdtrc_vals, label=f"$a= {a},\, b={b}$", ls=style)
5995 >>> ax.legend()
5996 >>> ax.set_xlabel("$x$")
5997 >>> ax.set_title("Gamma distribution survival function")
5998 >>> plt.show()
6000 The gamma distribution is also available as `scipy.stats.gamma`.
6001 Using `gdtrc` directly can be much faster than calling the ``sf`` method
6002 of `scipy.stats.gamma`, especially for small arrays or individual
6003 values. To get the same results one must use the following parametrization:
6004 ``stats.gamma(b, scale=1/a).sf(x)=gdtrc(a, b, x)``.
6006 >>> from scipy.stats import gamma
6007 >>> a = 2
6008 >>> b = 3
6009 >>> x = 1.
6010 >>> gdtrc_result = gdtrc(a, b, x) # this will often be faster than below
6011 >>> gamma_dist_result = gamma(b, scale=1/a).sf(x)
6012 >>> gdtrc_result == gamma_dist_result # test that results are equal
6013 True
6014 """)
6016add_newdoc("gdtria",
6017 """
6018 gdtria(p, b, x, out=None)
6020 Inverse of `gdtr` vs a.
6022 Returns the inverse with respect to the parameter `a` of ``p =
6023 gdtr(a, b, x)``, the cumulative distribution function of the gamma
6024 distribution.
6026 Parameters
6027 ----------
6028 p : array_like
6029 Probability values.
6030 b : array_like
6031 `b` parameter values of `gdtr(a, b, x)`. `b` is the "shape" parameter
6032 of the gamma distribution.
6033 x : array_like
6034 Nonnegative real values, from the domain of the gamma distribution.
6035 out : ndarray, optional
6036 If a fourth argument is given, it must be a numpy.ndarray whose size
6037 matches the broadcast result of `a`, `b` and `x`. `out` is then the
6038 array returned by the function.
6040 Returns
6041 -------
6042 a : scalar or ndarray
6043 Values of the `a` parameter such that `p = gdtr(a, b, x)`. `1/a`
6044 is the "scale" parameter of the gamma distribution.
6046 See Also
6047 --------
6048 gdtr : CDF of the gamma distribution.
6049 gdtrib : Inverse with respect to `b` of `gdtr(a, b, x)`.
6050 gdtrix : Inverse with respect to `x` of `gdtr(a, b, x)`.
6052 Notes
6053 -----
6054 Wrapper for the CDFLIB [1]_ Fortran routine `cdfgam`.
6056 The cumulative distribution function `p` is computed using a routine by
6057 DiDinato and Morris [2]_. Computation of `a` involves a search for a value
6058 that produces the desired value of `p`. The search relies on the
6059 monotonicity of `p` with `a`.
6061 References
6062 ----------
6063 .. [1] Barry Brown, James Lovato, and Kathy Russell,
6064 CDFLIB: Library of Fortran Routines for Cumulative Distribution
6065 Functions, Inverses, and Other Parameters.
6066 .. [2] DiDinato, A. R. and Morris, A. H.,
6067 Computation of the incomplete gamma function ratios and their
6068 inverse. ACM Trans. Math. Softw. 12 (1986), 377-393.
6070 Examples
6071 --------
6072 First evaluate `gdtr`.
6074 >>> from scipy.special import gdtr, gdtria
6075 >>> p = gdtr(1.2, 3.4, 5.6)
6076 >>> print(p)
6077 0.94378087442
6079 Verify the inverse.
6081 >>> gdtria(p, 3.4, 5.6)
6082 1.2
6083 """)
6085add_newdoc("gdtrib",
6086 """
6087 gdtrib(a, p, x, out=None)
6089 Inverse of `gdtr` vs b.
6091 Returns the inverse with respect to the parameter `b` of ``p =
6092 gdtr(a, b, x)``, the cumulative distribution function of the gamma
6093 distribution.
6095 Parameters
6096 ----------
6097 a : array_like
6098 `a` parameter values of `gdtr(a, b, x)`. `1/a` is the "scale"
6099 parameter of the gamma distribution.
6100 p : array_like
6101 Probability values.
6102 x : array_like
6103 Nonnegative real values, from the domain of the gamma distribution.
6104 out : ndarray, optional
6105 If a fourth argument is given, it must be a numpy.ndarray whose size
6106 matches the broadcast result of `a`, `b` and `x`. `out` is then the
6107 array returned by the function.
6109 Returns
6110 -------
6111 b : scalar or ndarray
6112 Values of the `b` parameter such that `p = gdtr(a, b, x)`. `b` is
6113 the "shape" parameter of the gamma distribution.
6115 See Also
6116 --------
6117 gdtr : CDF of the gamma distribution.
6118 gdtria : Inverse with respect to `a` of `gdtr(a, b, x)`.
6119 gdtrix : Inverse with respect to `x` of `gdtr(a, b, x)`.
6121 Notes
6122 -----
6123 Wrapper for the CDFLIB [1]_ Fortran routine `cdfgam`.
6125 The cumulative distribution function `p` is computed using a routine by
6126 DiDinato and Morris [2]_. Computation of `b` involves a search for a value
6127 that produces the desired value of `p`. The search relies on the
6128 monotonicity of `p` with `b`.
6130 References
6131 ----------
6132 .. [1] Barry Brown, James Lovato, and Kathy Russell,
6133 CDFLIB: Library of Fortran Routines for Cumulative Distribution
6134 Functions, Inverses, and Other Parameters.
6135 .. [2] DiDinato, A. R. and Morris, A. H.,
6136 Computation of the incomplete gamma function ratios and their
6137 inverse. ACM Trans. Math. Softw. 12 (1986), 377-393.
6139 Examples
6140 --------
6141 First evaluate `gdtr`.
6143 >>> from scipy.special import gdtr, gdtrib
6144 >>> p = gdtr(1.2, 3.4, 5.6)
6145 >>> print(p)
6146 0.94378087442
6148 Verify the inverse.
6150 >>> gdtrib(1.2, p, 5.6)
6151 3.3999999999723882
6152 """)
6154add_newdoc("gdtrix",
6155 """
6156 gdtrix(a, b, p, out=None)
6158 Inverse of `gdtr` vs x.
6160 Returns the inverse with respect to the parameter `x` of ``p =
6161 gdtr(a, b, x)``, the cumulative distribution function of the gamma
6162 distribution. This is also known as the pth quantile of the
6163 distribution.
6165 Parameters
6166 ----------
6167 a : array_like
6168 `a` parameter values of `gdtr(a, b, x)`. `1/a` is the "scale"
6169 parameter of the gamma distribution.
6170 b : array_like
6171 `b` parameter values of `gdtr(a, b, x)`. `b` is the "shape" parameter
6172 of the gamma distribution.
6173 p : array_like
6174 Probability values.
6175 out : ndarray, optional
6176 If a fourth argument is given, it must be a numpy.ndarray whose size
6177 matches the broadcast result of `a`, `b` and `x`. `out` is then the
6178 array returned by the function.
6180 Returns
6181 -------
6182 x : scalar or ndarray
6183 Values of the `x` parameter such that `p = gdtr(a, b, x)`.
6185 See Also
6186 --------
6187 gdtr : CDF of the gamma distribution.
6188 gdtria : Inverse with respect to `a` of `gdtr(a, b, x)`.
6189 gdtrib : Inverse with respect to `b` of `gdtr(a, b, x)`.
6191 Notes
6192 -----
6193 Wrapper for the CDFLIB [1]_ Fortran routine `cdfgam`.
6195 The cumulative distribution function `p` is computed using a routine by
6196 DiDinato and Morris [2]_. Computation of `x` involves a search for a value
6197 that produces the desired value of `p`. The search relies on the
6198 monotonicity of `p` with `x`.
6200 References
6201 ----------
6202 .. [1] Barry Brown, James Lovato, and Kathy Russell,
6203 CDFLIB: Library of Fortran Routines for Cumulative Distribution
6204 Functions, Inverses, and Other Parameters.
6205 .. [2] DiDinato, A. R. and Morris, A. H.,
6206 Computation of the incomplete gamma function ratios and their
6207 inverse. ACM Trans. Math. Softw. 12 (1986), 377-393.
6209 Examples
6210 --------
6211 First evaluate `gdtr`.
6213 >>> from scipy.special import gdtr, gdtrix
6214 >>> p = gdtr(1.2, 3.4, 5.6)
6215 >>> print(p)
6216 0.94378087442
6218 Verify the inverse.
6220 >>> gdtrix(1.2, 3.4, p)
6221 5.5999999999999996
6222 """)
6224add_newdoc("hankel1",
6225 r"""
6226 hankel1(v, z, out=None)
6228 Hankel function of the first kind
6230 Parameters
6231 ----------
6232 v : array_like
6233 Order (float).
6234 z : array_like
6235 Argument (float or complex).
6236 out : ndarray, optional
6237 Optional output array for the function values
6239 Returns
6240 -------
6241 scalar or ndarray
6242 Values of the Hankel function of the first kind.
6244 Notes
6245 -----
6246 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6247 computation using the relation,
6249 .. math:: H^{(1)}_v(z) = \frac{2}{\imath\pi} \exp(-\imath \pi v/2) K_v(z \exp(-\imath\pi/2))
6251 where :math:`K_v` is the modified Bessel function of the second kind.
6252 For negative orders, the relation
6254 .. math:: H^{(1)}_{-v}(z) = H^{(1)}_v(z) \exp(\imath\pi v)
6256 is used.
6258 See also
6259 --------
6260 hankel1e : ndarray
6261 This function with leading exponential behavior stripped off.
6263 References
6264 ----------
6265 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6266 of a Complex Argument and Nonnegative Order",
6267 http://netlib.org/amos/
6268 """)
6270add_newdoc("hankel1e",
6271 r"""
6272 hankel1e(v, z, out=None)
6274 Exponentially scaled Hankel function of the first kind
6276 Defined as::
6278 hankel1e(v, z) = hankel1(v, z) * exp(-1j * z)
6280 Parameters
6281 ----------
6282 v : array_like
6283 Order (float).
6284 z : array_like
6285 Argument (float or complex).
6286 out : ndarray, optional
6287 Optional output array for the function values
6289 Returns
6290 -------
6291 scalar or ndarray
6292 Values of the exponentially scaled Hankel function.
6294 Notes
6295 -----
6296 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6297 computation using the relation,
6299 .. math:: H^{(1)}_v(z) = \frac{2}{\imath\pi} \exp(-\imath \pi v/2) K_v(z \exp(-\imath\pi/2))
6301 where :math:`K_v` is the modified Bessel function of the second kind.
6302 For negative orders, the relation
6304 .. math:: H^{(1)}_{-v}(z) = H^{(1)}_v(z) \exp(\imath\pi v)
6306 is used.
6308 References
6309 ----------
6310 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6311 of a Complex Argument and Nonnegative Order",
6312 http://netlib.org/amos/
6313 """)
6315add_newdoc("hankel2",
6316 r"""
6317 hankel2(v, z, out=None)
6319 Hankel function of the second kind
6321 Parameters
6322 ----------
6323 v : array_like
6324 Order (float).
6325 z : array_like
6326 Argument (float or complex).
6327 out : ndarray, optional
6328 Optional output array for the function values
6330 Returns
6331 -------
6332 scalar or ndarray
6333 Values of the Hankel function of the second kind.
6335 Notes
6336 -----
6337 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6338 computation using the relation,
6340 .. math:: H^{(2)}_v(z) = -\frac{2}{\imath\pi} \exp(\imath \pi v/2) K_v(z \exp(\imath\pi/2))
6342 where :math:`K_v` is the modified Bessel function of the second kind.
6343 For negative orders, the relation
6345 .. math:: H^{(2)}_{-v}(z) = H^{(2)}_v(z) \exp(-\imath\pi v)
6347 is used.
6349 See also
6350 --------
6351 hankel2e : this function with leading exponential behavior stripped off.
6353 References
6354 ----------
6355 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6356 of a Complex Argument and Nonnegative Order",
6357 http://netlib.org/amos/
6358 """)
6360add_newdoc("hankel2e",
6361 r"""
6362 hankel2e(v, z, out=None)
6364 Exponentially scaled Hankel function of the second kind
6366 Defined as::
6368 hankel2e(v, z) = hankel2(v, z) * exp(1j * z)
6370 Parameters
6371 ----------
6372 v : array_like
6373 Order (float).
6374 z : array_like
6375 Argument (float or complex).
6376 out : ndarray, optional
6377 Optional output array for the function values
6379 Returns
6380 -------
6381 scalar or ndarray
6382 Values of the exponentially scaled Hankel function of the second kind.
6384 Notes
6385 -----
6386 A wrapper for the AMOS [1]_ routine `zbesh`, which carries out the
6387 computation using the relation,
6389 .. math:: H^{(2)}_v(z) = -\frac{2}{\imath\pi} \exp(\frac{\imath \pi v}{2}) K_v(z exp(\frac{\imath\pi}{2}))
6391 where :math:`K_v` is the modified Bessel function of the second kind.
6392 For negative orders, the relation
6394 .. math:: H^{(2)}_{-v}(z) = H^{(2)}_v(z) \exp(-\imath\pi v)
6396 is used.
6398 References
6399 ----------
6400 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
6401 of a Complex Argument and Nonnegative Order",
6402 http://netlib.org/amos/
6404 """)
6406add_newdoc("huber",
6407 r"""
6408 huber(delta, r, out=None)
6410 Huber loss function.
6412 .. 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}
6414 Parameters
6415 ----------
6416 delta : ndarray
6417 Input array, indicating the quadratic vs. linear loss changepoint.
6418 r : ndarray
6419 Input array, possibly representing residuals.
6420 out : ndarray, optional
6421 Optional output array for the function values
6423 Returns
6424 -------
6425 scalar or ndarray
6426 The computed Huber loss function values.
6428 See also
6429 --------
6430 pseudo_huber : smooth approximation of this function
6432 Notes
6433 -----
6434 `huber` is useful as a loss function in robust statistics or machine
6435 learning to reduce the influence of outliers as compared to the common
6436 squared error loss, residuals with a magnitude higher than `delta` are
6437 not squared [1]_.
6439 Typically, `r` represents residuals, the difference
6440 between a model prediction and data. Then, for :math:`|r|\leq\delta`,
6441 `huber` resembles the squared error and for :math:`|r|>\delta` the
6442 absolute error. This way, the Huber loss often achieves
6443 a fast convergence in model fitting for small residuals like the squared
6444 error loss function and still reduces the influence of outliers
6445 (:math:`|r|>\delta`) like the absolute error loss. As :math:`\delta` is
6446 the cutoff between squared and absolute error regimes, it has
6447 to be tuned carefully for each problem. `huber` is also
6448 convex, making it suitable for gradient based optimization.
6450 .. versionadded:: 0.15.0
6452 References
6453 ----------
6454 .. [1] Peter Huber. "Robust Estimation of a Location Parameter",
6455 1964. Annals of Statistics. 53 (1): 73 - 101.
6457 Examples
6458 --------
6459 Import all necessary modules.
6461 >>> import numpy as np
6462 >>> from scipy.special import huber
6463 >>> import matplotlib.pyplot as plt
6465 Compute the function for ``delta=1`` at ``r=2``
6467 >>> huber(1., 2.)
6468 1.5
6470 Compute the function for different `delta` by providing a NumPy array or
6471 list for `delta`.
6473 >>> huber([1., 3., 5.], 4.)
6474 array([3.5, 7.5, 8. ])
6476 Compute the function at different points by providing a NumPy array or
6477 list for `r`.
6479 >>> huber(2., np.array([1., 1.5, 3.]))
6480 array([0.5 , 1.125, 4. ])
6482 The function can be calculated for different `delta` and `r` by
6483 providing arrays for both with compatible shapes for broadcasting.
6485 >>> r = np.array([1., 2.5, 8., 10.])
6486 >>> deltas = np.array([[1.], [5.], [9.]])
6487 >>> print(r.shape, deltas.shape)
6488 (4,) (3, 1)
6490 >>> huber(deltas, r)
6491 array([[ 0.5 , 2. , 7.5 , 9.5 ],
6492 [ 0.5 , 3.125, 27.5 , 37.5 ],
6493 [ 0.5 , 3.125, 32. , 49.5 ]])
6495 Plot the function for different `delta`.
6497 >>> x = np.linspace(-4, 4, 500)
6498 >>> deltas = [1, 2, 3]
6499 >>> linestyles = ["dashed", "dotted", "dashdot"]
6500 >>> fig, ax = plt.subplots()
6501 >>> combined_plot_parameters = list(zip(deltas, linestyles))
6502 >>> for delta, style in combined_plot_parameters:
6503 ... ax.plot(x, huber(delta, x), label=f"$\delta={delta}$", ls=style)
6504 >>> ax.legend(loc="upper center")
6505 >>> ax.set_xlabel("$x$")
6506 >>> ax.set_title("Huber loss function $h_{\delta}(x)$")
6507 >>> ax.set_xlim(-4, 4)
6508 >>> ax.set_ylim(0, 8)
6509 >>> plt.show()
6510 """)
6512add_newdoc("hyp0f1",
6513 r"""
6514 hyp0f1(v, z, out=None)
6516 Confluent hypergeometric limit function 0F1.
6518 Parameters
6519 ----------
6520 v : array_like
6521 Real-valued parameter
6522 z : array_like
6523 Real- or complex-valued argument
6524 out : ndarray, optional
6525 Optional output array for the function results
6527 Returns
6528 -------
6529 scalar or ndarray
6530 The confluent hypergeometric limit function
6532 Notes
6533 -----
6534 This function is defined as:
6536 .. math:: _0F_1(v, z) = \sum_{k=0}^{\infty}\frac{z^k}{(v)_k k!}.
6538 It's also the limit as :math:`q \to \infty` of :math:`_1F_1(q; v; z/q)`,
6539 and satisfies the differential equation :math:`f''(z) + vf'(z) =
6540 f(z)`. See [1]_ for more information.
6542 References
6543 ----------
6544 .. [1] Wolfram MathWorld, "Confluent Hypergeometric Limit Function",
6545 http://mathworld.wolfram.com/ConfluentHypergeometricLimitFunction.html
6547 Examples
6548 --------
6549 >>> import numpy as np
6550 >>> import scipy.special as sc
6552 It is one when `z` is zero.
6554 >>> sc.hyp0f1(1, 0)
6555 1.0
6557 It is the limit of the confluent hypergeometric function as `q`
6558 goes to infinity.
6560 >>> q = np.array([1, 10, 100, 1000])
6561 >>> v = 1
6562 >>> z = 1
6563 >>> sc.hyp1f1(q, v, z / q)
6564 array([2.71828183, 2.31481985, 2.28303778, 2.27992985])
6565 >>> sc.hyp0f1(v, z)
6566 2.2795853023360673
6568 It is related to Bessel functions.
6570 >>> n = 1
6571 >>> x = np.linspace(0, 1, 5)
6572 >>> sc.jv(n, x)
6573 array([0. , 0.12402598, 0.24226846, 0.3492436 , 0.44005059])
6574 >>> (0.5 * x)**n / sc.factorial(n) * sc.hyp0f1(n + 1, -0.25 * x**2)
6575 array([0. , 0.12402598, 0.24226846, 0.3492436 , 0.44005059])
6577 """)
6579add_newdoc("hyp1f1",
6580 r"""
6581 hyp1f1(a, b, x, out=None)
6583 Confluent hypergeometric function 1F1.
6585 The confluent hypergeometric function is defined by the series
6587 .. math::
6589 {}_1F_1(a; b; x) = \sum_{k = 0}^\infty \frac{(a)_k}{(b)_k k!} x^k.
6591 See [dlmf]_ for more details. Here :math:`(\cdot)_k` is the
6592 Pochhammer symbol; see `poch`.
6594 Parameters
6595 ----------
6596 a, b : array_like
6597 Real parameters
6598 x : array_like
6599 Real or complex argument
6600 out : ndarray, optional
6601 Optional output array for the function results
6603 Returns
6604 -------
6605 scalar or ndarray
6606 Values of the confluent hypergeometric function
6608 See also
6609 --------
6610 hyperu : another confluent hypergeometric function
6611 hyp0f1 : confluent hypergeometric limit function
6612 hyp2f1 : Gaussian hypergeometric function
6614 References
6615 ----------
6616 .. [dlmf] NIST Digital Library of Mathematical Functions
6617 https://dlmf.nist.gov/13.2#E2
6619 Examples
6620 --------
6621 >>> import numpy as np
6622 >>> import scipy.special as sc
6624 It is one when `x` is zero:
6626 >>> sc.hyp1f1(0.5, 0.5, 0)
6627 1.0
6629 It is singular when `b` is a nonpositive integer.
6631 >>> sc.hyp1f1(0.5, -1, 0)
6632 inf
6634 It is a polynomial when `a` is a nonpositive integer.
6636 >>> a, b, x = -1, 0.5, np.array([1.0, 2.0, 3.0, 4.0])
6637 >>> sc.hyp1f1(a, b, x)
6638 array([-1., -3., -5., -7.])
6639 >>> 1 + (a / b) * x
6640 array([-1., -3., -5., -7.])
6642 It reduces to the exponential function when `a = b`.
6644 >>> sc.hyp1f1(2, 2, [1, 2, 3, 4])
6645 array([ 2.71828183, 7.3890561 , 20.08553692, 54.59815003])
6646 >>> np.exp([1, 2, 3, 4])
6647 array([ 2.71828183, 7.3890561 , 20.08553692, 54.59815003])
6649 """)
6651add_newdoc("hyp2f1",
6652 r"""
6653 hyp2f1(a, b, c, z, out=None)
6655 Gauss hypergeometric function 2F1(a, b; c; z)
6657 Parameters
6658 ----------
6659 a, b, c : array_like
6660 Arguments, should be real-valued.
6661 z : array_like
6662 Argument, real or complex.
6663 out : ndarray, optional
6664 Optional output array for the function values
6666 Returns
6667 -------
6668 hyp2f1 : scalar or ndarray
6669 The values of the gaussian hypergeometric function.
6671 See also
6672 --------
6673 hyp0f1 : confluent hypergeometric limit function.
6674 hyp1f1 : Kummer's (confluent hypergeometric) function.
6676 Notes
6677 -----
6678 This function is defined for :math:`|z| < 1` as
6680 .. math::
6682 \mathrm{hyp2f1}(a, b, c, z) = \sum_{n=0}^\infty
6683 \frac{(a)_n (b)_n}{(c)_n}\frac{z^n}{n!},
6685 and defined on the rest of the complex z-plane by analytic
6686 continuation [1]_.
6687 Here :math:`(\cdot)_n` is the Pochhammer symbol; see `poch`. When
6688 :math:`n` is an integer the result is a polynomial of degree :math:`n`.
6690 The implementation for complex values of ``z`` is described in [2]_,
6691 except for ``z`` in the region defined by
6693 .. math::
6695 0.9 <= \left|z\right| < 1.1,
6696 \left|1 - z\right| >= 0.9,
6697 \mathrm{real}(z) >= 0
6699 in which the implementation follows [4]_.
6701 References
6702 ----------
6703 .. [1] NIST Digital Library of Mathematical Functions
6704 https://dlmf.nist.gov/15.2
6705 .. [2] S. Zhang and J.M. Jin, "Computation of Special Functions", Wiley 1996
6706 .. [3] Cephes Mathematical Functions Library,
6707 http://www.netlib.org/cephes/
6708 .. [4] J.L. Lopez and N.M. Temme, "New series expansions of the Gauss
6709 hypergeometric function", Adv Comput Math 39, 349-365 (2013).
6710 https://doi.org/10.1007/s10444-012-9283-y
6712 Examples
6713 --------
6714 >>> import numpy as np
6715 >>> import scipy.special as sc
6717 It has poles when `c` is a negative integer.
6719 >>> sc.hyp2f1(1, 1, -2, 1)
6720 inf
6722 It is a polynomial when `a` or `b` is a negative integer.
6724 >>> a, b, c = -1, 1, 1.5
6725 >>> z = np.linspace(0, 1, 5)
6726 >>> sc.hyp2f1(a, b, c, z)
6727 array([1. , 0.83333333, 0.66666667, 0.5 , 0.33333333])
6728 >>> 1 + a * b * z / c
6729 array([1. , 0.83333333, 0.66666667, 0.5 , 0.33333333])
6731 It is symmetric in `a` and `b`.
6733 >>> a = np.linspace(0, 1, 5)
6734 >>> b = np.linspace(0, 1, 5)
6735 >>> sc.hyp2f1(a, b, 1, 0.5)
6736 array([1. , 1.03997334, 1.1803406 , 1.47074441, 2. ])
6737 >>> sc.hyp2f1(b, a, 1, 0.5)
6738 array([1. , 1.03997334, 1.1803406 , 1.47074441, 2. ])
6740 It contains many other functions as special cases.
6742 >>> z = 0.5
6743 >>> sc.hyp2f1(1, 1, 2, z)
6744 1.3862943611198901
6745 >>> -np.log(1 - z) / z
6746 1.3862943611198906
6748 >>> sc.hyp2f1(0.5, 1, 1.5, z**2)
6749 1.098612288668109
6750 >>> np.log((1 + z) / (1 - z)) / (2 * z)
6751 1.0986122886681098
6753 >>> sc.hyp2f1(0.5, 1, 1.5, -z**2)
6754 0.9272952180016117
6755 >>> np.arctan(z) / z
6756 0.9272952180016122
6758 """)
6760add_newdoc("hyperu",
6761 r"""
6762 hyperu(a, b, x, out=None)
6764 Confluent hypergeometric function U
6766 It is defined as the solution to the equation
6768 .. math::
6770 x \frac{d^2w}{dx^2} + (b - x) \frac{dw}{dx} - aw = 0
6772 which satisfies the property
6774 .. math::
6776 U(a, b, x) \sim x^{-a}
6778 as :math:`x \to \infty`. See [dlmf]_ for more details.
6780 Parameters
6781 ----------
6782 a, b : array_like
6783 Real-valued parameters
6784 x : array_like
6785 Real-valued argument
6786 out : ndarray, optional
6787 Optional output array for the function values
6789 Returns
6790 -------
6791 scalar or ndarray
6792 Values of `U`
6794 References
6795 ----------
6796 .. [dlmf] NIST Digital Library of Mathematics Functions
6797 https://dlmf.nist.gov/13.2#E6
6799 Examples
6800 --------
6801 >>> import numpy as np
6802 >>> import scipy.special as sc
6804 It has a branch cut along the negative `x` axis.
6806 >>> x = np.linspace(-0.1, -10, 5)
6807 >>> sc.hyperu(1, 1, x)
6808 array([nan, nan, nan, nan, nan])
6810 It approaches zero as `x` goes to infinity.
6812 >>> x = np.array([1, 10, 100])
6813 >>> sc.hyperu(1, 1, x)
6814 array([0.59634736, 0.09156333, 0.00990194])
6816 It satisfies Kummer's transformation.
6818 >>> a, b, x = 2, 1, 1
6819 >>> sc.hyperu(a, b, x)
6820 0.1926947246463881
6821 >>> x**(1 - b) * sc.hyperu(a - b + 1, 2 - b, x)
6822 0.1926947246463881
6824 """)
6826add_newdoc("i0",
6827 r"""
6828 i0(x, out=None)
6830 Modified Bessel function of order 0.
6832 Defined as,
6834 .. math::
6835 I_0(x) = \sum_{k=0}^\infty \frac{(x^2/4)^k}{(k!)^2} = J_0(\imath x),
6837 where :math:`J_0` is the Bessel function of the first kind of order 0.
6839 Parameters
6840 ----------
6841 x : array_like
6842 Argument (float)
6843 out : ndarray, optional
6844 Optional output array for the function values
6846 Returns
6847 -------
6848 I : scalar or ndarray
6849 Value of the modified Bessel function of order 0 at `x`.
6851 Notes
6852 -----
6853 The range is partitioned into the two intervals [0, 8] and (8, infinity).
6854 Chebyshev polynomial expansions are employed in each interval.
6856 This function is a wrapper for the Cephes [1]_ routine `i0`.
6858 See also
6859 --------
6860 iv: Modified Bessel function of any order
6861 i0e: Exponentially scaled modified Bessel function of order 0
6863 References
6864 ----------
6865 .. [1] Cephes Mathematical Functions Library,
6866 http://www.netlib.org/cephes/
6868 Examples
6869 --------
6870 Calculate the function at one point:
6872 >>> from scipy.special import i0
6873 >>> i0(1.)
6874 1.2660658777520082
6876 Calculate at several points:
6878 >>> import numpy as np
6879 >>> i0(np.array([-2., 0., 3.5]))
6880 array([2.2795853 , 1. , 7.37820343])
6882 Plot the function from -10 to 10.
6884 >>> import matplotlib.pyplot as plt
6885 >>> fig, ax = plt.subplots()
6886 >>> x = np.linspace(-10., 10., 1000)
6887 >>> y = i0(x)
6888 >>> ax.plot(x, y)
6889 >>> plt.show()
6891 """)
6893add_newdoc("i0e",
6894 """
6895 i0e(x, out=None)
6897 Exponentially scaled modified Bessel function of order 0.
6899 Defined as::
6901 i0e(x) = exp(-abs(x)) * i0(x).
6903 Parameters
6904 ----------
6905 x : array_like
6906 Argument (float)
6907 out : ndarray, optional
6908 Optional output array for the function values
6910 Returns
6911 -------
6912 I : scalar or ndarray
6913 Value of the exponentially scaled modified Bessel function of order 0
6914 at `x`.
6916 Notes
6917 -----
6918 The range is partitioned into the two intervals [0, 8] and (8, infinity).
6919 Chebyshev polynomial expansions are employed in each interval. The
6920 polynomial expansions used are the same as those in `i0`, but
6921 they are not multiplied by the dominant exponential factor.
6923 This function is a wrapper for the Cephes [1]_ routine `i0e`.
6925 See also
6926 --------
6927 iv: Modified Bessel function of the first kind
6928 i0: Modified Bessel function of order 0
6930 References
6931 ----------
6932 .. [1] Cephes Mathematical Functions Library,
6933 http://www.netlib.org/cephes/
6935 Examples
6936 --------
6937 Calculate the function at one point:
6939 >>> from scipy.special import i0e
6940 >>> i0e(1.)
6941 0.46575960759364043
6943 Calculate the function at several points:
6945 >>> import numpy as np
6946 >>> i0e(np.array([-2., 0., 3.]))
6947 array([0.30850832, 1. , 0.24300035])
6949 Plot the function from -10 to 10.
6951 >>> import matplotlib.pyplot as plt
6952 >>> fig, ax = plt.subplots()
6953 >>> x = np.linspace(-10., 10., 1000)
6954 >>> y = i0e(x)
6955 >>> ax.plot(x, y)
6956 >>> plt.show()
6958 Exponentially scaled Bessel functions are useful for large arguments for
6959 which the unscaled Bessel functions overflow or lose precision. In the
6960 following example `i0` returns infinity whereas `i0e` still returns
6961 a finite number.
6963 >>> from scipy.special import i0
6964 >>> i0(1000.), i0e(1000.)
6965 (inf, 0.012617240455891257)
6966 """)
6968add_newdoc("i1",
6969 r"""
6970 i1(x, out=None)
6972 Modified Bessel function of order 1.
6974 Defined as,
6976 .. math::
6977 I_1(x) = \frac{1}{2}x \sum_{k=0}^\infty \frac{(x^2/4)^k}{k! (k + 1)!}
6978 = -\imath J_1(\imath x),
6980 where :math:`J_1` is the Bessel function of the first kind of order 1.
6982 Parameters
6983 ----------
6984 x : array_like
6985 Argument (float)
6986 out : ndarray, optional
6987 Optional output array for the function values
6989 Returns
6990 -------
6991 I : scalar or ndarray
6992 Value of the modified Bessel function of order 1 at `x`.
6994 Notes
6995 -----
6996 The range is partitioned into the two intervals [0, 8] and (8, infinity).
6997 Chebyshev polynomial expansions are employed in each interval.
6999 This function is a wrapper for the Cephes [1]_ routine `i1`.
7001 See also
7002 --------
7003 iv: Modified Bessel function of the first kind
7004 i1e: Exponentially scaled modified Bessel function of order 1
7006 References
7007 ----------
7008 .. [1] Cephes Mathematical Functions Library,
7009 http://www.netlib.org/cephes/
7011 Examples
7012 --------
7013 Calculate the function at one point:
7015 >>> from scipy.special import i1
7016 >>> i1(1.)
7017 0.5651591039924851
7019 Calculate the function at several points:
7021 >>> import numpy as np
7022 >>> i1(np.array([-2., 0., 6.]))
7023 array([-1.59063685, 0. , 61.34193678])
7025 Plot the function between -10 and 10.
7027 >>> import matplotlib.pyplot as plt
7028 >>> fig, ax = plt.subplots()
7029 >>> x = np.linspace(-10., 10., 1000)
7030 >>> y = i1(x)
7031 >>> ax.plot(x, y)
7032 >>> plt.show()
7034 """)
7036add_newdoc("i1e",
7037 """
7038 i1e(x, out=None)
7040 Exponentially scaled modified Bessel function of order 1.
7042 Defined as::
7044 i1e(x) = exp(-abs(x)) * i1(x)
7046 Parameters
7047 ----------
7048 x : array_like
7049 Argument (float)
7050 out : ndarray, optional
7051 Optional output array for the function values
7053 Returns
7054 -------
7055 I : scalar or ndarray
7056 Value of the exponentially scaled modified Bessel function of order 1
7057 at `x`.
7059 Notes
7060 -----
7061 The range is partitioned into the two intervals [0, 8] and (8, infinity).
7062 Chebyshev polynomial expansions are employed in each interval. The
7063 polynomial expansions used are the same as those in `i1`, but
7064 they are not multiplied by the dominant exponential factor.
7066 This function is a wrapper for the Cephes [1]_ routine `i1e`.
7068 See also
7069 --------
7070 iv: Modified Bessel function of the first kind
7071 i1: Modified Bessel function of order 1
7073 References
7074 ----------
7075 .. [1] Cephes Mathematical Functions Library,
7076 http://www.netlib.org/cephes/
7078 Examples
7079 --------
7080 Calculate the function at one point:
7082 >>> from scipy.special import i1e
7083 >>> i1e(1.)
7084 0.2079104153497085
7086 Calculate the function at several points:
7088 >>> import numpy as np
7089 >>> i1e(np.array([-2., 0., 6.]))
7090 array([-0.21526929, 0. , 0.15205146])
7092 Plot the function between -10 and 10.
7094 >>> import matplotlib.pyplot as plt
7095 >>> fig, ax = plt.subplots()
7096 >>> x = np.linspace(-10., 10., 1000)
7097 >>> y = i1e(x)
7098 >>> ax.plot(x, y)
7099 >>> plt.show()
7101 Exponentially scaled Bessel functions are useful for large arguments for
7102 which the unscaled Bessel functions overflow or lose precision. In the
7103 following example `i1` returns infinity whereas `i1e` still returns a
7104 finite number.
7106 >>> from scipy.special import i1
7107 >>> i1(1000.), i1e(1000.)
7108 (inf, 0.01261093025692863)
7109 """)
7111add_newdoc("_igam_fac",
7112 """
7113 Internal function, do not use.
7114 """)
7116add_newdoc("it2i0k0",
7117 r"""
7118 it2i0k0(x, out=None)
7120 Integrals related to modified Bessel functions of order 0.
7122 Computes the integrals
7124 .. math::
7126 \int_0^x \frac{I_0(t) - 1}{t} dt \\
7127 \int_x^\infty \frac{K_0(t)}{t} dt.
7129 Parameters
7130 ----------
7131 x : array_like
7132 Values at which to evaluate the integrals.
7133 out : tuple of ndarrays, optional
7134 Optional output arrays for the function results.
7136 Returns
7137 -------
7138 ii0 : scalar or ndarray
7139 The integral for `i0`
7140 ik0 : scalar or ndarray
7141 The integral for `k0`
7143 References
7144 ----------
7145 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7146 Wiley 1996
7148 Examples
7149 --------
7150 Evaluate the functions at one point.
7152 >>> from scipy.special import it2i0k0
7153 >>> int_i, int_k = it2i0k0(1.)
7154 >>> int_i, int_k
7155 (0.12897944249456852, 0.2085182909001295)
7157 Evaluate the functions at several points.
7159 >>> import numpy as np
7160 >>> points = np.array([0.5, 1.5, 3.])
7161 >>> int_i, int_k = it2i0k0(points)
7162 >>> int_i, int_k
7163 (array([0.03149527, 0.30187149, 1.50012461]),
7164 array([0.66575102, 0.0823715 , 0.00823631]))
7166 Plot the functions from 0 to 5.
7168 >>> import matplotlib.pyplot as plt
7169 >>> fig, ax = plt.subplots()
7170 >>> x = np.linspace(0., 5., 1000)
7171 >>> int_i, int_k = it2i0k0(x)
7172 >>> ax.plot(x, int_i, label=r"$\int_0^x \frac{I_0(t)-1}{t}\,dt$")
7173 >>> ax.plot(x, int_k, label=r"$\int_x^{\infty} \frac{K_0(t)}{t}\,dt$")
7174 >>> ax.legend()
7175 >>> ax.set_ylim(0, 10)
7176 >>> plt.show()
7177 """)
7179add_newdoc("it2j0y0",
7180 r"""
7181 it2j0y0(x, out=None)
7183 Integrals related to Bessel functions of the first kind of order 0.
7185 Computes the integrals
7187 .. math::
7189 \int_0^x \frac{1 - J_0(t)}{t} dt \\
7190 \int_x^\infty \frac{Y_0(t)}{t} dt.
7192 For more on :math:`J_0` and :math:`Y_0` see `j0` and `y0`.
7194 Parameters
7195 ----------
7196 x : array_like
7197 Values at which to evaluate the integrals.
7198 out : tuple of ndarrays, optional
7199 Optional output arrays for the function results.
7201 Returns
7202 -------
7203 ij0 : scalar or ndarray
7204 The integral for `j0`
7205 iy0 : scalar or ndarray
7206 The integral for `y0`
7208 References
7209 ----------
7210 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7211 Wiley 1996
7213 Examples
7214 --------
7215 Evaluate the functions at one point.
7217 >>> from scipy.special import it2j0y0
7218 >>> int_j, int_y = it2j0y0(1.)
7219 >>> int_j, int_y
7220 (0.12116524699506871, 0.39527290169929336)
7222 Evaluate the functions at several points.
7224 >>> import numpy as np
7225 >>> points = np.array([0.5, 1.5, 3.])
7226 >>> int_j, int_y = it2j0y0(points)
7227 >>> int_j, int_y
7228 (array([0.03100699, 0.26227724, 0.85614669]),
7229 array([ 0.26968854, 0.29769696, -0.02987272]))
7231 Plot the functions from 0 to 10.
7233 >>> import matplotlib.pyplot as plt
7234 >>> fig, ax = plt.subplots()
7235 >>> x = np.linspace(0., 10., 1000)
7236 >>> int_j, int_y = it2j0y0(x)
7237 >>> ax.plot(x, int_j, label=r"$\int_0^x \frac{1-J_0(t)}{t}\,dt$")
7238 >>> ax.plot(x, int_y, label=r"$\int_x^{\infty} \frac{Y_0(t)}{t}\,dt$")
7239 >>> ax.legend()
7240 >>> ax.set_ylim(-2.5, 2.5)
7241 >>> plt.show()
7242 """)
7244add_newdoc("it2struve0",
7245 r"""
7246 it2struve0(x, out=None)
7248 Integral related to the Struve function of order 0.
7250 Returns the integral,
7252 .. math::
7253 \int_x^\infty \frac{H_0(t)}{t}\,dt
7255 where :math:`H_0` is the Struve function of order 0.
7257 Parameters
7258 ----------
7259 x : array_like
7260 Lower limit of integration.
7261 out : ndarray, optional
7262 Optional output array for the function values
7264 Returns
7265 -------
7266 I : scalar or ndarray
7267 The value of the integral.
7269 See also
7270 --------
7271 struve
7273 Notes
7274 -----
7275 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7276 Jin [1]_.
7278 References
7279 ----------
7280 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7281 Functions", John Wiley and Sons, 1996.
7282 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7284 Examples
7285 --------
7286 Evaluate the function at one point.
7288 >>> import numpy as np
7289 >>> from scipy.special import it2struve0
7290 >>> it2struve0(1.)
7291 0.9571973506383524
7293 Evaluate the function at several points by supplying
7294 an array for `x`.
7296 >>> points = np.array([1., 2., 3.5])
7297 >>> it2struve0(points)
7298 array([0.95719735, 0.46909296, 0.10366042])
7300 Plot the function from -10 to 10.
7302 >>> import matplotlib.pyplot as plt
7303 >>> x = np.linspace(-10., 10., 1000)
7304 >>> it2struve0_values = it2struve0(x)
7305 >>> fig, ax = plt.subplots()
7306 >>> ax.plot(x, it2struve0_values)
7307 >>> ax.set_xlabel(r'$x$')
7308 >>> ax.set_ylabel(r'$\int_x^{\infty}\frac{H_0(t)}{t}\,dt$')
7309 >>> plt.show()
7310 """)
7312add_newdoc(
7313 "itairy",
7314 r"""
7315 itairy(x, out=None)
7317 Integrals of Airy functions
7319 Calculates the integrals of Airy functions from 0 to `x`.
7321 Parameters
7322 ----------
7324 x : array_like
7325 Upper limit of integration (float).
7326 out : tuple of ndarray, optional
7327 Optional output arrays for the function values
7329 Returns
7330 -------
7331 Apt : scalar or ndarray
7332 Integral of Ai(t) from 0 to x.
7333 Bpt : scalar or ndarray
7334 Integral of Bi(t) from 0 to x.
7335 Ant : scalar or ndarray
7336 Integral of Ai(-t) from 0 to x.
7337 Bnt : scalar or ndarray
7338 Integral of Bi(-t) from 0 to x.
7340 Notes
7341 -----
7343 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7344 Jin [1]_.
7346 References
7347 ----------
7349 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7350 Functions", John Wiley and Sons, 1996.
7351 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7353 Examples
7354 --------
7355 Compute the functions at ``x=1.``.
7357 >>> import numpy as np
7358 >>> from scipy.special import itairy
7359 >>> import matplotlib.pyplot as plt
7360 >>> apt, bpt, ant, bnt = itairy(1.)
7361 >>> apt, bpt, ant, bnt
7362 (0.23631734191710949,
7363 0.8727691167380077,
7364 0.46567398346706845,
7365 0.3730050096342943)
7367 Compute the functions at several points by providing a NumPy array for `x`.
7369 >>> x = np.array([1., 1.5, 2.5, 5])
7370 >>> apt, bpt, ant, bnt = itairy(x)
7371 >>> apt, bpt, ant, bnt
7372 (array([0.23631734, 0.28678675, 0.324638 , 0.33328759]),
7373 array([ 0.87276912, 1.62470809, 5.20906691, 321.47831857]),
7374 array([0.46567398, 0.72232876, 0.93187776, 0.7178822 ]),
7375 array([ 0.37300501, 0.35038814, -0.02812939, 0.15873094]))
7377 Plot the functions from -10 to 10.
7379 >>> x = np.linspace(-10, 10, 500)
7380 >>> apt, bpt, ant, bnt = itairy(x)
7381 >>> fig, ax = plt.subplots(figsize=(6, 5))
7382 >>> ax.plot(x, apt, label="$\int_0^x\, Ai(t)\, dt$")
7383 >>> ax.plot(x, bpt, ls="dashed", label="$\int_0^x\, Bi(t)\, dt$")
7384 >>> ax.plot(x, ant, ls="dashdot", label="$\int_0^x\, Ai(-t)\, dt$")
7385 >>> ax.plot(x, bnt, ls="dotted", label="$\int_0^x\, Bi(-t)\, dt$")
7386 >>> ax.set_ylim(-2, 1.5)
7387 >>> ax.legend(loc="lower right")
7388 >>> plt.show()
7389 """)
7391add_newdoc("iti0k0",
7392 r"""
7393 iti0k0(x, out=None)
7395 Integrals of modified Bessel functions of order 0.
7397 Computes the integrals
7399 .. math::
7401 \int_0^x I_0(t) dt \\
7402 \int_0^x K_0(t) dt.
7404 For more on :math:`I_0` and :math:`K_0` see `i0` and `k0`.
7406 Parameters
7407 ----------
7408 x : array_like
7409 Values at which to evaluate the integrals.
7410 out : tuple of ndarrays, optional
7411 Optional output arrays for the function results.
7413 Returns
7414 -------
7415 ii0 : scalar or ndarray
7416 The integral for `i0`
7417 ik0 : scalar or ndarray
7418 The integral for `k0`
7420 References
7421 ----------
7422 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7423 Wiley 1996
7425 Examples
7426 --------
7427 Evaluate the functions at one point.
7429 >>> from scipy.special import iti0k0
7430 >>> int_i, int_k = iti0k0(1.)
7431 >>> int_i, int_k
7432 (1.0865210970235892, 1.2425098486237771)
7434 Evaluate the functions at several points.
7436 >>> import numpy as np
7437 >>> points = np.array([0., 1.5, 3.])
7438 >>> int_i, int_k = iti0k0(points)
7439 >>> int_i, int_k
7440 (array([0. , 1.80606937, 6.16096149]),
7441 array([0. , 1.39458246, 1.53994809]))
7443 Plot the functions from 0 to 5.
7445 >>> import matplotlib.pyplot as plt
7446 >>> fig, ax = plt.subplots()
7447 >>> x = np.linspace(0., 5., 1000)
7448 >>> int_i, int_k = iti0k0(x)
7449 >>> ax.plot(x, int_i, label="$\int_0^x I_0(t)\,dt$")
7450 >>> ax.plot(x, int_k, label="$\int_0^x K_0(t)\,dt$")
7451 >>> ax.legend()
7452 >>> plt.show()
7453 """)
7455add_newdoc("itj0y0",
7456 r"""
7457 itj0y0(x, out=None)
7459 Integrals of Bessel functions of the first kind of order 0.
7461 Computes the integrals
7463 .. math::
7465 \int_0^x J_0(t) dt \\
7466 \int_0^x Y_0(t) dt.
7468 For more on :math:`J_0` and :math:`Y_0` see `j0` and `y0`.
7470 Parameters
7471 ----------
7472 x : array_like
7473 Values at which to evaluate the integrals.
7474 out : tuple of ndarrays, optional
7475 Optional output arrays for the function results.
7477 Returns
7478 -------
7479 ij0 : scalar or ndarray
7480 The integral of `j0`
7481 iy0 : scalar or ndarray
7482 The integral of `y0`
7484 References
7485 ----------
7486 .. [1] S. Zhang and J.M. Jin, "Computation of Special Functions",
7487 Wiley 1996
7489 Examples
7490 --------
7491 Evaluate the functions at one point.
7493 >>> from scipy.special import itj0y0
7494 >>> int_j, int_y = itj0y0(1.)
7495 >>> int_j, int_y
7496 (0.9197304100897596, -0.637069376607422)
7498 Evaluate the functions at several points.
7500 >>> import numpy as np
7501 >>> points = np.array([0., 1.5, 3.])
7502 >>> int_j, int_y = itj0y0(points)
7503 >>> int_j, int_y
7504 (array([0. , 1.24144951, 1.38756725]),
7505 array([ 0. , -0.51175903, 0.19765826]))
7507 Plot the functions from 0 to 10.
7509 >>> import matplotlib.pyplot as plt
7510 >>> fig, ax = plt.subplots()
7511 >>> x = np.linspace(0., 10., 1000)
7512 >>> int_j, int_y = itj0y0(x)
7513 >>> ax.plot(x, int_j, label="$\int_0^x J_0(t)\,dt$")
7514 >>> ax.plot(x, int_y, label="$\int_0^x Y_0(t)\,dt$")
7515 >>> ax.legend()
7516 >>> plt.show()
7518 """)
7520add_newdoc("itmodstruve0",
7521 r"""
7522 itmodstruve0(x, out=None)
7524 Integral of the modified Struve function of order 0.
7526 .. math::
7527 I = \int_0^x L_0(t)\,dt
7529 Parameters
7530 ----------
7531 x : array_like
7532 Upper limit of integration (float).
7533 out : ndarray, optional
7534 Optional output array for the function values
7536 Returns
7537 -------
7538 I : scalar or ndarray
7539 The integral of :math:`L_0` from 0 to `x`.
7541 Notes
7542 -----
7543 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7544 Jin [1]_.
7546 See Also
7547 --------
7548 modstruve: Modified Struve function which is integrated by this function
7550 References
7551 ----------
7552 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7553 Functions", John Wiley and Sons, 1996.
7554 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7556 Examples
7557 --------
7558 Evaluate the function at one point.
7560 >>> import numpy as np
7561 >>> from scipy.special import itmodstruve0
7562 >>> itmodstruve0(1.)
7563 0.3364726286440384
7565 Evaluate the function at several points by supplying
7566 an array for `x`.
7568 >>> points = np.array([1., 2., 3.5])
7569 >>> itmodstruve0(points)
7570 array([0.33647263, 1.588285 , 7.60382578])
7572 Plot the function from -10 to 10.
7574 >>> import matplotlib.pyplot as plt
7575 >>> x = np.linspace(-10., 10., 1000)
7576 >>> itmodstruve0_values = itmodstruve0(x)
7577 >>> fig, ax = plt.subplots()
7578 >>> ax.plot(x, itmodstruve0_values)
7579 >>> ax.set_xlabel(r'$x$')
7580 >>> ax.set_ylabel(r'$\int_0^xL_0(t)\,dt$')
7581 >>> plt.show()
7582 """)
7584add_newdoc("itstruve0",
7585 r"""
7586 itstruve0(x, out=None)
7588 Integral of the Struve function of order 0.
7590 .. math::
7591 I = \int_0^x H_0(t)\,dt
7593 Parameters
7594 ----------
7595 x : array_like
7596 Upper limit of integration (float).
7597 out : ndarray, optional
7598 Optional output array for the function values
7600 Returns
7601 -------
7602 I : scalar or ndarray
7603 The integral of :math:`H_0` from 0 to `x`.
7605 See also
7606 --------
7607 struve: Function which is integrated by this function
7609 Notes
7610 -----
7611 Wrapper for a Fortran routine created by Shanjie Zhang and Jianming
7612 Jin [1]_.
7614 References
7615 ----------
7616 .. [1] Zhang, Shanjie and Jin, Jianming. "Computation of Special
7617 Functions", John Wiley and Sons, 1996.
7618 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
7620 Examples
7621 --------
7622 Evaluate the function at one point.
7624 >>> import numpy as np
7625 >>> from scipy.special import itstruve0
7626 >>> itstruve0(1.)
7627 0.30109042670805547
7629 Evaluate the function at several points by supplying
7630 an array for `x`.
7632 >>> points = np.array([1., 2., 3.5])
7633 >>> itstruve0(points)
7634 array([0.30109043, 1.01870116, 1.96804581])
7636 Plot the function from -20 to 20.
7638 >>> import matplotlib.pyplot as plt
7639 >>> x = np.linspace(-20., 20., 1000)
7640 >>> istruve0_values = itstruve0(x)
7641 >>> fig, ax = plt.subplots()
7642 >>> ax.plot(x, istruve0_values)
7643 >>> ax.set_xlabel(r'$x$')
7644 >>> ax.set_ylabel(r'$\int_0^{x}H_0(t)\,dt$')
7645 >>> plt.show()
7646 """)
7648add_newdoc("iv",
7649 r"""
7650 iv(v, z, out=None)
7652 Modified Bessel function of the first kind of real order.
7654 Parameters
7655 ----------
7656 v : array_like
7657 Order. If `z` is of real type and negative, `v` must be integer
7658 valued.
7659 z : array_like of float or complex
7660 Argument.
7661 out : ndarray, optional
7662 Optional output array for the function values
7664 Returns
7665 -------
7666 scalar or ndarray
7667 Values of the modified Bessel function.
7669 Notes
7670 -----
7671 For real `z` and :math:`v \in [-50, 50]`, the evaluation is carried out
7672 using Temme's method [1]_. For larger orders, uniform asymptotic
7673 expansions are applied.
7675 For complex `z` and positive `v`, the AMOS [2]_ `zbesi` routine is
7676 called. It uses a power series for small `z`, the asymptotic expansion
7677 for large `abs(z)`, the Miller algorithm normalized by the Wronskian
7678 and a Neumann series for intermediate magnitudes, and the uniform
7679 asymptotic expansions for :math:`I_v(z)` and :math:`J_v(z)` for large
7680 orders. Backward recurrence is used to generate sequences or reduce
7681 orders when necessary.
7683 The calculations above are done in the right half plane and continued
7684 into the left half plane by the formula,
7686 .. math:: I_v(z \exp(\pm\imath\pi)) = \exp(\pm\pi v) I_v(z)
7688 (valid when the real part of `z` is positive). For negative `v`, the
7689 formula
7691 .. math:: I_{-v}(z) = I_v(z) + \frac{2}{\pi} \sin(\pi v) K_v(z)
7693 is used, where :math:`K_v(z)` is the modified Bessel function of the
7694 second kind, evaluated using the AMOS routine `zbesk`.
7696 See also
7697 --------
7698 ive : This function with leading exponential behavior stripped off.
7699 i0 : Faster version of this function for order 0.
7700 i1 : Faster version of this function for order 1.
7702 References
7703 ----------
7704 .. [1] Temme, Journal of Computational Physics, vol 21, 343 (1976)
7705 .. [2] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
7706 of a Complex Argument and Nonnegative Order",
7707 http://netlib.org/amos/
7709 Examples
7710 --------
7711 Evaluate the function of order 0 at one point.
7713 >>> from scipy.special import iv
7714 >>> iv(0, 1.)
7715 1.2660658777520084
7717 Evaluate the function at one point for different orders.
7719 >>> iv(0, 1.), iv(1, 1.), iv(1.5, 1.)
7720 (1.2660658777520084, 0.565159103992485, 0.2935253263474798)
7722 The evaluation for different orders can be carried out in one call by
7723 providing a list or NumPy array as argument for the `v` parameter:
7725 >>> iv([0, 1, 1.5], 1.)
7726 array([1.26606588, 0.5651591 , 0.29352533])
7728 Evaluate the function at several points for order 0 by providing an
7729 array for `z`.
7731 >>> import numpy as np
7732 >>> points = np.array([-2., 0., 3.])
7733 >>> iv(0, points)
7734 array([2.2795853 , 1. , 4.88079259])
7736 If `z` is an array, the order parameter `v` must be broadcastable to
7737 the correct shape if different orders shall be computed in one call.
7738 To calculate the orders 0 and 1 for an 1D array:
7740 >>> orders = np.array([[0], [1]])
7741 >>> orders.shape
7742 (2, 1)
7744 >>> iv(orders, points)
7745 array([[ 2.2795853 , 1. , 4.88079259],
7746 [-1.59063685, 0. , 3.95337022]])
7748 Plot the functions of order 0 to 3 from -5 to 5.
7750 >>> import matplotlib.pyplot as plt
7751 >>> fig, ax = plt.subplots()
7752 >>> x = np.linspace(-5., 5., 1000)
7753 >>> for i in range(4):
7754 ... ax.plot(x, iv(i, x), label=f'$I_{i!r}$')
7755 >>> ax.legend()
7756 >>> plt.show()
7758 """)
7760add_newdoc("ive",
7761 r"""
7762 ive(v, z, out=None)
7764 Exponentially scaled modified Bessel function of the first kind.
7766 Defined as::
7768 ive(v, z) = iv(v, z) * exp(-abs(z.real))
7770 For imaginary numbers without a real part, returns the unscaled
7771 Bessel function of the first kind `iv`.
7773 Parameters
7774 ----------
7775 v : array_like of float
7776 Order.
7777 z : array_like of float or complex
7778 Argument.
7779 out : ndarray, optional
7780 Optional output array for the function values
7782 Returns
7783 -------
7784 scalar or ndarray
7785 Values of the exponentially scaled modified Bessel function.
7787 Notes
7788 -----
7789 For positive `v`, the AMOS [1]_ `zbesi` routine is called. It uses a
7790 power series for small `z`, the asymptotic expansion for large
7791 `abs(z)`, the Miller algorithm normalized by the Wronskian and a
7792 Neumann series for intermediate magnitudes, and the uniform asymptotic
7793 expansions for :math:`I_v(z)` and :math:`J_v(z)` for large orders.
7794 Backward recurrence is used to generate sequences or reduce orders when
7795 necessary.
7797 The calculations above are done in the right half plane and continued
7798 into the left half plane by the formula,
7800 .. math:: I_v(z \exp(\pm\imath\pi)) = \exp(\pm\pi v) I_v(z)
7802 (valid when the real part of `z` is positive). For negative `v`, the
7803 formula
7805 .. math:: I_{-v}(z) = I_v(z) + \frac{2}{\pi} \sin(\pi v) K_v(z)
7807 is used, where :math:`K_v(z)` is the modified Bessel function of the
7808 second kind, evaluated using the AMOS routine `zbesk`.
7810 See also
7811 --------
7812 iv: Modified Bessel function of the first kind
7813 i0e: Faster implementation of this function for order 0
7814 i1e: Faster implementation of this function for order 1
7816 References
7817 ----------
7818 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
7819 of a Complex Argument and Nonnegative Order",
7820 http://netlib.org/amos/
7822 Examples
7823 --------
7824 Evaluate the function of order 0 at one point.
7826 >>> import numpy as np
7827 >>> from scipy.special import iv, ive
7828 >>> import matplotlib.pyplot as plt
7829 >>> ive(0, 1.)
7830 0.4657596075936404
7832 Evaluate the function at one point for different orders by
7833 providing a list or NumPy array as argument for the `v` parameter:
7835 >>> ive([0, 1, 1.5], 1.)
7836 array([0.46575961, 0.20791042, 0.10798193])
7838 Evaluate the function at several points for order 0 by providing an
7839 array for `z`.
7841 >>> points = np.array([-2., 0., 3.])
7842 >>> ive(0, points)
7843 array([0.30850832, 1. , 0.24300035])
7845 Evaluate the function at several points for different orders by
7846 providing arrays for both `v` for `z`. Both arrays have to be
7847 broadcastable to the correct shape. To calculate the orders 0, 1
7848 and 2 for a 1D array of points:
7850 >>> ive([[0], [1], [2]], points)
7851 array([[ 0.30850832, 1. , 0.24300035],
7852 [-0.21526929, 0. , 0.19682671],
7853 [ 0.09323903, 0. , 0.11178255]])
7855 Plot the functions of order 0 to 3 from -5 to 5.
7857 >>> fig, ax = plt.subplots()
7858 >>> x = np.linspace(-5., 5., 1000)
7859 >>> for i in range(4):
7860 ... ax.plot(x, ive(i, x), label=f'$I_{i!r}(z)\cdot e^{{-|z|}}$')
7861 >>> ax.legend()
7862 >>> ax.set_xlabel(r"$z$")
7863 >>> plt.show()
7865 Exponentially scaled Bessel functions are useful for large arguments for
7866 which the unscaled Bessel functions over- or underflow. In the
7867 following example `iv` returns infinity whereas `ive` still returns
7868 a finite number.
7870 >>> iv(3, 1000.), ive(3, 1000.)
7871 (inf, 0.01256056218254712)
7872 """)
7874add_newdoc("j0",
7875 r"""
7876 j0(x, out=None)
7878 Bessel function of the first kind of order 0.
7880 Parameters
7881 ----------
7882 x : array_like
7883 Argument (float).
7884 out : ndarray, optional
7885 Optional output array for the function values
7887 Returns
7888 -------
7889 J : scalar or ndarray
7890 Value of the Bessel function of the first kind of order 0 at `x`.
7892 Notes
7893 -----
7894 The domain is divided into the intervals [0, 5] and (5, infinity). In the
7895 first interval the following rational approximation is used:
7897 .. math::
7899 J_0(x) \approx (w - r_1^2)(w - r_2^2) \frac{P_3(w)}{Q_8(w)},
7901 where :math:`w = x^2` and :math:`r_1`, :math:`r_2` are the zeros of
7902 :math:`J_0`, and :math:`P_3` and :math:`Q_8` are polynomials of degrees 3
7903 and 8, respectively.
7905 In the second interval, the Hankel asymptotic expansion is employed with
7906 two rational functions of degree 6/6 and 7/7.
7908 This function is a wrapper for the Cephes [1]_ routine `j0`.
7909 It should not be confused with the spherical Bessel functions (see
7910 `spherical_jn`).
7912 See also
7913 --------
7914 jv : Bessel function of real order and complex argument.
7915 spherical_jn : spherical Bessel functions.
7917 References
7918 ----------
7919 .. [1] Cephes Mathematical Functions Library,
7920 http://www.netlib.org/cephes/
7922 Examples
7923 --------
7924 Calculate the function at one point:
7926 >>> from scipy.special import j0
7927 >>> j0(1.)
7928 0.7651976865579665
7930 Calculate the function at several points:
7932 >>> import numpy as np
7933 >>> j0(np.array([-2., 0., 4.]))
7934 array([ 0.22389078, 1. , -0.39714981])
7936 Plot the function from -20 to 20.
7938 >>> import matplotlib.pyplot as plt
7939 >>> fig, ax = plt.subplots()
7940 >>> x = np.linspace(-20., 20., 1000)
7941 >>> y = j0(x)
7942 >>> ax.plot(x, y)
7943 >>> plt.show()
7945 """)
7947add_newdoc("j1",
7948 """
7949 j1(x, out=None)
7951 Bessel function of the first kind of order 1.
7953 Parameters
7954 ----------
7955 x : array_like
7956 Argument (float).
7957 out : ndarray, optional
7958 Optional output array for the function values
7960 Returns
7961 -------
7962 J : scalar or ndarray
7963 Value of the Bessel function of the first kind of order 1 at `x`.
7965 Notes
7966 -----
7967 The domain is divided into the intervals [0, 8] and (8, infinity). In the
7968 first interval a 24 term Chebyshev expansion is used. In the second, the
7969 asymptotic trigonometric representation is employed using two rational
7970 functions of degree 5/5.
7972 This function is a wrapper for the Cephes [1]_ routine `j1`.
7973 It should not be confused with the spherical Bessel functions (see
7974 `spherical_jn`).
7976 See also
7977 --------
7978 jv: Bessel function of the first kind
7979 spherical_jn: spherical Bessel functions.
7981 References
7982 ----------
7983 .. [1] Cephes Mathematical Functions Library,
7984 http://www.netlib.org/cephes/
7986 Examples
7987 --------
7988 Calculate the function at one point:
7990 >>> from scipy.special import j1
7991 >>> j1(1.)
7992 0.44005058574493355
7994 Calculate the function at several points:
7996 >>> import numpy as np
7997 >>> j1(np.array([-2., 0., 4.]))
7998 array([-0.57672481, 0. , -0.06604333])
8000 Plot the function from -20 to 20.
8002 >>> import matplotlib.pyplot as plt
8003 >>> fig, ax = plt.subplots()
8004 >>> x = np.linspace(-20., 20., 1000)
8005 >>> y = j1(x)
8006 >>> ax.plot(x, y)
8007 >>> plt.show()
8009 """)
8011add_newdoc("jn",
8012 """
8013 jn(n, x, out=None)
8015 Bessel function of the first kind of integer order and real argument.
8017 Parameters
8018 ----------
8019 n : array_like
8020 order of the Bessel function
8021 x : array_like
8022 argument of the Bessel function
8023 out : ndarray, optional
8024 Optional output array for the function values
8026 Returns
8027 -------
8028 scalar or ndarray
8029 The value of the bessel function
8031 See also
8032 --------
8033 jv
8034 spherical_jn : spherical Bessel functions.
8036 Notes
8037 -----
8038 `jn` is an alias of `jv`.
8039 Not to be confused with the spherical Bessel functions (see
8040 `spherical_jn`).
8042 """)
8044add_newdoc("jv",
8045 r"""
8046 jv(v, z, out=None)
8048 Bessel function of the first kind of real order and complex argument.
8050 Parameters
8051 ----------
8052 v : array_like
8053 Order (float).
8054 z : array_like
8055 Argument (float or complex).
8056 out : ndarray, optional
8057 Optional output array for the function values
8059 Returns
8060 -------
8061 J : scalar or ndarray
8062 Value of the Bessel function, :math:`J_v(z)`.
8064 See also
8065 --------
8066 jve : :math:`J_v` with leading exponential behavior stripped off.
8067 spherical_jn : spherical Bessel functions.
8068 j0 : faster version of this function for order 0.
8069 j1 : faster version of this function for order 1.
8071 Notes
8072 -----
8073 For positive `v` values, the computation is carried out using the AMOS
8074 [1]_ `zbesj` routine, which exploits the connection to the modified
8075 Bessel function :math:`I_v`,
8077 .. math::
8078 J_v(z) = \exp(v\pi\imath/2) I_v(-\imath z)\qquad (\Im z > 0)
8080 J_v(z) = \exp(-v\pi\imath/2) I_v(\imath z)\qquad (\Im z < 0)
8082 For negative `v` values the formula,
8084 .. math:: J_{-v}(z) = J_v(z) \cos(\pi v) - Y_v(z) \sin(\pi v)
8086 is used, where :math:`Y_v(z)` is the Bessel function of the second
8087 kind, computed using the AMOS routine `zbesy`. Note that the second
8088 term is exactly zero for integer `v`; to improve accuracy the second
8089 term is explicitly omitted for `v` values such that `v = floor(v)`.
8091 Not to be confused with the spherical Bessel functions (see `spherical_jn`).
8093 References
8094 ----------
8095 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
8096 of a Complex Argument and Nonnegative Order",
8097 http://netlib.org/amos/
8099 Examples
8100 --------
8101 Evaluate the function of order 0 at one point.
8103 >>> from scipy.special import jv
8104 >>> jv(0, 1.)
8105 0.7651976865579666
8107 Evaluate the function at one point for different orders.
8109 >>> jv(0, 1.), jv(1, 1.), jv(1.5, 1.)
8110 (0.7651976865579666, 0.44005058574493355, 0.24029783912342725)
8112 The evaluation for different orders can be carried out in one call by
8113 providing a list or NumPy array as argument for the `v` parameter:
8115 >>> jv([0, 1, 1.5], 1.)
8116 array([0.76519769, 0.44005059, 0.24029784])
8118 Evaluate the function at several points for order 0 by providing an
8119 array for `z`.
8121 >>> import numpy as np
8122 >>> points = np.array([-2., 0., 3.])
8123 >>> jv(0, points)
8124 array([ 0.22389078, 1. , -0.26005195])
8126 If `z` is an array, the order parameter `v` must be broadcastable to
8127 the correct shape if different orders shall be computed in one call.
8128 To calculate the orders 0 and 1 for an 1D array:
8130 >>> orders = np.array([[0], [1]])
8131 >>> orders.shape
8132 (2, 1)
8134 >>> jv(orders, points)
8135 array([[ 0.22389078, 1. , -0.26005195],
8136 [-0.57672481, 0. , 0.33905896]])
8138 Plot the functions of order 0 to 3 from -10 to 10.
8140 >>> import matplotlib.pyplot as plt
8141 >>> fig, ax = plt.subplots()
8142 >>> x = np.linspace(-10., 10., 1000)
8143 >>> for i in range(4):
8144 ... ax.plot(x, jv(i, x), label=f'$J_{i!r}$')
8145 >>> ax.legend()
8146 >>> plt.show()
8148 """)
8150add_newdoc("jve",
8151 r"""
8152 jve(v, z, out=None)
8154 Exponentially scaled Bessel function of the first kind of order `v`.
8156 Defined as::
8158 jve(v, z) = jv(v, z) * exp(-abs(z.imag))
8160 Parameters
8161 ----------
8162 v : array_like
8163 Order (float).
8164 z : array_like
8165 Argument (float or complex).
8166 out : ndarray, optional
8167 Optional output array for the function values
8169 Returns
8170 -------
8171 J : scalar or ndarray
8172 Value of the exponentially scaled Bessel function.
8174 See also
8175 --------
8176 jv: Unscaled Bessel function of the first kind
8178 Notes
8179 -----
8180 For positive `v` values, the computation is carried out using the AMOS
8181 [1]_ `zbesj` routine, which exploits the connection to the modified
8182 Bessel function :math:`I_v`,
8184 .. math::
8185 J_v(z) = \exp(v\pi\imath/2) I_v(-\imath z)\qquad (\Im z > 0)
8187 J_v(z) = \exp(-v\pi\imath/2) I_v(\imath z)\qquad (\Im z < 0)
8189 For negative `v` values the formula,
8191 .. math:: J_{-v}(z) = J_v(z) \cos(\pi v) - Y_v(z) \sin(\pi v)
8193 is used, where :math:`Y_v(z)` is the Bessel function of the second
8194 kind, computed using the AMOS routine `zbesy`. Note that the second
8195 term is exactly zero for integer `v`; to improve accuracy the second
8196 term is explicitly omitted for `v` values such that `v = floor(v)`.
8198 Exponentially scaled Bessel functions are useful for large arguments `z`:
8199 for these, the unscaled Bessel functions can easily under-or overflow.
8201 References
8202 ----------
8203 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
8204 of a Complex Argument and Nonnegative Order",
8205 http://netlib.org/amos/
8207 Examples
8208 --------
8209 Compare the output of `jv` and `jve` for large complex arguments for `z`
8210 by computing their values for order ``v=1`` at ``z=1000j``. We see that
8211 `jv` overflows but `jve` returns a finite number:
8213 >>> import numpy as np
8214 >>> from scipy.special import jv, jve
8215 >>> v = 1
8216 >>> z = 1000j
8217 >>> jv(v, z), jve(v, z)
8218 ((inf+infj), (7.721967686709077e-19+0.012610930256928629j))
8220 For real arguments for `z`, `jve` returns the same as `jv`.
8222 >>> v, z = 1, 1000
8223 >>> jv(v, z), jve(v, z)
8224 (0.004728311907089523, 0.004728311907089523)
8226 The function can be evaluated for several orders at the same time by
8227 providing a list or NumPy array for `v`:
8229 >>> jve([1, 3, 5], 1j)
8230 array([1.27304208e-17+2.07910415e-01j, -4.99352086e-19-8.15530777e-03j,
8231 6.11480940e-21+9.98657141e-05j])
8233 In the same way, the function can be evaluated at several points in one
8234 call by providing a list or NumPy array for `z`:
8236 >>> jve(1, np.array([1j, 2j, 3j]))
8237 array([1.27308412e-17+0.20791042j, 1.31814423e-17+0.21526929j,
8238 1.20521602e-17+0.19682671j])
8240 It is also possible to evaluate several orders at several points
8241 at the same time by providing arrays for `v` and `z` with
8242 compatible shapes for broadcasting. Compute `jve` for two different orders
8243 `v` and three points `z` resulting in a 2x3 array.
8245 >>> v = np.array([[1], [3]])
8246 >>> z = np.array([1j, 2j, 3j])
8247 >>> v.shape, z.shape
8248 ((2, 1), (3,))
8250 >>> jve(v, z)
8251 array([[1.27304208e-17+0.20791042j, 1.31810070e-17+0.21526929j,
8252 1.20517622e-17+0.19682671j],
8253 [-4.99352086e-19-0.00815531j, -1.76289571e-18-0.02879122j,
8254 -2.92578784e-18-0.04778332j]])
8255 """)
8257add_newdoc("k0",
8258 r"""
8259 k0(x, out=None)
8261 Modified Bessel function of the second kind of order 0, :math:`K_0`.
8263 This function is also sometimes referred to as the modified Bessel
8264 function of the third kind of order 0.
8266 Parameters
8267 ----------
8268 x : array_like
8269 Argument (float).
8270 out : ndarray, optional
8271 Optional output array for the function values
8273 Returns
8274 -------
8275 K : scalar or ndarray
8276 Value of the modified Bessel function :math:`K_0` at `x`.
8278 Notes
8279 -----
8280 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8281 Chebyshev polynomial expansions are employed in each interval.
8283 This function is a wrapper for the Cephes [1]_ routine `k0`.
8285 See also
8286 --------
8287 kv: Modified Bessel function of the second kind of any order
8288 k0e: Exponentially scaled modified Bessel function of the second kind
8290 References
8291 ----------
8292 .. [1] Cephes Mathematical Functions Library,
8293 http://www.netlib.org/cephes/
8295 Examples
8296 --------
8297 Calculate the function at one point:
8299 >>> from scipy.special import k0
8300 >>> k0(1.)
8301 0.42102443824070823
8303 Calculate the function at several points:
8305 >>> import numpy as np
8306 >>> k0(np.array([0.5, 2., 3.]))
8307 array([0.92441907, 0.11389387, 0.0347395 ])
8309 Plot the function from 0 to 10.
8311 >>> import matplotlib.pyplot as plt
8312 >>> fig, ax = plt.subplots()
8313 >>> x = np.linspace(0., 10., 1000)
8314 >>> y = k0(x)
8315 >>> ax.plot(x, y)
8316 >>> plt.show()
8318 """)
8320add_newdoc("k0e",
8321 """
8322 k0e(x, out=None)
8324 Exponentially scaled modified Bessel function K of order 0
8326 Defined as::
8328 k0e(x) = exp(x) * k0(x).
8330 Parameters
8331 ----------
8332 x : array_like
8333 Argument (float)
8334 out : ndarray, optional
8335 Optional output array for the function values
8337 Returns
8338 -------
8339 K : scalar or ndarray
8340 Value of the exponentially scaled modified Bessel function K of order
8341 0 at `x`.
8343 Notes
8344 -----
8345 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8346 Chebyshev polynomial expansions are employed in each interval.
8348 This function is a wrapper for the Cephes [1]_ routine `k0e`.
8350 See also
8351 --------
8352 kv: Modified Bessel function of the second kind of any order
8353 k0: Modified Bessel function of the second kind
8355 References
8356 ----------
8357 .. [1] Cephes Mathematical Functions Library,
8358 http://www.netlib.org/cephes/
8360 Examples
8361 --------
8362 Calculate the function at one point:
8364 >>> from scipy.special import k0e
8365 >>> k0e(1.)
8366 1.1444630798068947
8368 Calculate the function at several points:
8370 >>> import numpy as np
8371 >>> k0e(np.array([0.5, 2., 3.]))
8372 array([1.52410939, 0.84156822, 0.6977616 ])
8374 Plot the function from 0 to 10.
8376 >>> import matplotlib.pyplot as plt
8377 >>> fig, ax = plt.subplots()
8378 >>> x = np.linspace(0., 10., 1000)
8379 >>> y = k0e(x)
8380 >>> ax.plot(x, y)
8381 >>> plt.show()
8383 Exponentially scaled Bessel functions are useful for large arguments for
8384 which the unscaled Bessel functions are not precise enough.
8386 >>> from scipy.special import k0
8387 >>> k0(1000.)
8388 0.
8390 While `k0` returns zero, `k0e` still returns a finite number:
8392 >>> k0e(1000.)
8393 0.03962832160075422
8395 """)
8397add_newdoc("k1",
8398 """
8399 k1(x, out=None)
8401 Modified Bessel function of the second kind of order 1, :math:`K_1(x)`.
8403 Parameters
8404 ----------
8405 x : array_like
8406 Argument (float)
8407 out : ndarray, optional
8408 Optional output array for the function values
8410 Returns
8411 -------
8412 K : scalar or ndarray
8413 Value of the modified Bessel function K of order 1 at `x`.
8415 Notes
8416 -----
8417 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8418 Chebyshev polynomial expansions are employed in each interval.
8420 This function is a wrapper for the Cephes [1]_ routine `k1`.
8422 See also
8423 --------
8424 kv: Modified Bessel function of the second kind of any order
8425 k1e: Exponentially scaled modified Bessel function K of order 1
8427 References
8428 ----------
8429 .. [1] Cephes Mathematical Functions Library,
8430 http://www.netlib.org/cephes/
8432 Examples
8433 --------
8434 Calculate the function at one point:
8436 >>> from scipy.special import k1
8437 >>> k1(1.)
8438 0.6019072301972346
8440 Calculate the function at several points:
8442 >>> import numpy as np
8443 >>> k1(np.array([0.5, 2., 3.]))
8444 array([1.65644112, 0.13986588, 0.04015643])
8446 Plot the function from 0 to 10.
8448 >>> import matplotlib.pyplot as plt
8449 >>> fig, ax = plt.subplots()
8450 >>> x = np.linspace(0., 10., 1000)
8451 >>> y = k1(x)
8452 >>> ax.plot(x, y)
8453 >>> plt.show()
8455 """)
8457add_newdoc("k1e",
8458 """
8459 k1e(x, out=None)
8461 Exponentially scaled modified Bessel function K of order 1
8463 Defined as::
8465 k1e(x) = exp(x) * k1(x)
8467 Parameters
8468 ----------
8469 x : array_like
8470 Argument (float)
8471 out : ndarray, optional
8472 Optional output array for the function values
8474 Returns
8475 -------
8476 K : scalar or ndarray
8477 Value of the exponentially scaled modified Bessel function K of order
8478 1 at `x`.
8480 Notes
8481 -----
8482 The range is partitioned into the two intervals [0, 2] and (2, infinity).
8483 Chebyshev polynomial expansions are employed in each interval.
8485 This function is a wrapper for the Cephes [1]_ routine `k1e`.
8487 See also
8488 --------
8489 kv: Modified Bessel function of the second kind of any order
8490 k1: Modified Bessel function of the second kind of order 1
8492 References
8493 ----------
8494 .. [1] Cephes Mathematical Functions Library,
8495 http://www.netlib.org/cephes/
8497 Examples
8498 --------
8499 Calculate the function at one point:
8501 >>> from scipy.special import k1e
8502 >>> k1e(1.)
8503 1.636153486263258
8505 Calculate the function at several points:
8507 >>> import numpy as np
8508 >>> k1e(np.array([0.5, 2., 3.]))
8509 array([2.73100971, 1.03347685, 0.80656348])
8511 Plot the function from 0 to 10.
8513 >>> import matplotlib.pyplot as plt
8514 >>> fig, ax = plt.subplots()
8515 >>> x = np.linspace(0., 10., 1000)
8516 >>> y = k1e(x)
8517 >>> ax.plot(x, y)
8518 >>> plt.show()
8520 Exponentially scaled Bessel functions are useful for large arguments for
8521 which the unscaled Bessel functions are not precise enough. In the
8522 following example `k1` returns zero whereas `k1e` still returns a
8523 useful floating point number.
8525 >>> from scipy.special import k1
8526 >>> k1(1000.), k1e(1000.)
8527 (0., 0.03964813081296021)
8528 """)
8530add_newdoc("kei",
8531 r"""
8532 kei(x, out=None)
8534 Kelvin function kei.
8536 Defined as
8538 .. math::
8540 \mathrm{kei}(x) = \Im[K_0(x e^{\pi i / 4})]
8542 where :math:`K_0` is the modified Bessel function of the second
8543 kind (see `kv`). See [dlmf]_ for more details.
8545 Parameters
8546 ----------
8547 x : array_like
8548 Real argument.
8549 out : ndarray, optional
8550 Optional output array for the function results.
8552 Returns
8553 -------
8554 scalar or ndarray
8555 Values of the Kelvin function.
8557 See Also
8558 --------
8559 ker : the corresponding real part
8560 keip : the derivative of kei
8561 kv : modified Bessel function of the second kind
8563 References
8564 ----------
8565 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8566 https://dlmf.nist.gov/10.61
8568 Examples
8569 --------
8570 It can be expressed using the modified Bessel function of the
8571 second kind.
8573 >>> import numpy as np
8574 >>> import scipy.special as sc
8575 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
8576 >>> sc.kv(0, x * np.exp(np.pi * 1j / 4)).imag
8577 array([-0.49499464, -0.20240007, -0.05112188, 0.0021984 ])
8578 >>> sc.kei(x)
8579 array([-0.49499464, -0.20240007, -0.05112188, 0.0021984 ])
8581 """)
8583add_newdoc("keip",
8584 r"""
8585 keip(x, out=None)
8587 Derivative of the Kelvin function kei.
8589 Parameters
8590 ----------
8591 x : array_like
8592 Real argument.
8593 out : ndarray, optional
8594 Optional output array for the function results.
8596 Returns
8597 -------
8598 scalar or ndarray
8599 The values of the derivative of kei.
8601 See Also
8602 --------
8603 kei
8605 References
8606 ----------
8607 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8608 https://dlmf.nist.gov/10#PT5
8610 """)
8612add_newdoc("kelvin",
8613 """
8614 kelvin(x, out=None)
8616 Kelvin functions as complex numbers
8618 Parameters
8619 ----------
8620 x : array_like
8621 Argument
8622 out : tuple of ndarray, optional
8623 Optional output arrays for the function values
8625 Returns
8626 -------
8627 Be, Ke, Bep, Kep : 4-tuple of scalar or ndarray
8628 The tuple (Be, Ke, Bep, Kep) contains complex numbers
8629 representing the real and imaginary Kelvin functions and their
8630 derivatives evaluated at `x`. For example, kelvin(x)[0].real =
8631 ber x and kelvin(x)[0].imag = bei x with similar relationships
8632 for ker and kei.
8633 """)
8635add_newdoc("ker",
8636 r"""
8637 ker(x, out=None)
8639 Kelvin function ker.
8641 Defined as
8643 .. math::
8645 \mathrm{ker}(x) = \Re[K_0(x e^{\pi i / 4})]
8647 Where :math:`K_0` is the modified Bessel function of the second
8648 kind (see `kv`). See [dlmf]_ for more details.
8650 Parameters
8651 ----------
8652 x : array_like
8653 Real argument.
8654 out : ndarray, optional
8655 Optional output array for the function results.
8657 Returns
8658 -------
8659 scalar or ndarray
8660 Values of the Kelvin function.
8662 See Also
8663 --------
8664 kei : the corresponding imaginary part
8665 kerp : the derivative of ker
8666 kv : modified Bessel function of the second kind
8668 References
8669 ----------
8670 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8671 https://dlmf.nist.gov/10.61
8673 Examples
8674 --------
8675 It can be expressed using the modified Bessel function of the
8676 second kind.
8678 >>> import numpy as np
8679 >>> import scipy.special as sc
8680 >>> x = np.array([1.0, 2.0, 3.0, 4.0])
8681 >>> sc.kv(0, x * np.exp(np.pi * 1j / 4)).real
8682 array([ 0.28670621, -0.04166451, -0.06702923, -0.03617885])
8683 >>> sc.ker(x)
8684 array([ 0.28670621, -0.04166451, -0.06702923, -0.03617885])
8686 """)
8688add_newdoc("kerp",
8689 r"""
8690 kerp(x, out=None)
8692 Derivative of the Kelvin function ker.
8694 Parameters
8695 ----------
8696 x : array_like
8697 Real argument.
8698 out : ndarray, optional
8699 Optional output array for the function results.
8701 Returns
8702 -------
8703 scalar or ndarray
8704 Values of the derivative of ker.
8706 See Also
8707 --------
8708 ker
8710 References
8711 ----------
8712 .. [dlmf] NIST, Digital Library of Mathematical Functions,
8713 https://dlmf.nist.gov/10#PT5
8715 """)
8717add_newdoc("kl_div",
8718 r"""
8719 kl_div(x, y, out=None)
8721 Elementwise function for computing Kullback-Leibler divergence.
8723 .. math::
8725 \mathrm{kl\_div}(x, y) =
8726 \begin{cases}
8727 x \log(x / y) - x + y & x > 0, y > 0 \\
8728 y & x = 0, y \ge 0 \\
8729 \infty & \text{otherwise}
8730 \end{cases}
8732 Parameters
8733 ----------
8734 x, y : array_like
8735 Real arguments
8736 out : ndarray, optional
8737 Optional output array for the function results
8739 Returns
8740 -------
8741 scalar or ndarray
8742 Values of the Kullback-Liebler divergence.
8744 See Also
8745 --------
8746 entr, rel_entr, scipy.stats.entropy
8748 Notes
8749 -----
8750 .. versionadded:: 0.15.0
8752 This function is non-negative and is jointly convex in `x` and `y`.
8754 The origin of this function is in convex programming; see [1]_ for
8755 details. This is why the function contains the extra :math:`-x
8756 + y` terms over what might be expected from the Kullback-Leibler
8757 divergence. For a version of the function without the extra terms,
8758 see `rel_entr`.
8760 References
8761 ----------
8762 .. [1] Boyd, Stephen and Lieven Vandenberghe. *Convex optimization*.
8763 Cambridge University Press, 2004.
8764 :doi:`https://doi.org/10.1017/CBO9780511804441`
8766 """)
8768add_newdoc("kn",
8769 r"""
8770 kn(n, x, out=None)
8772 Modified Bessel function of the second kind of integer order `n`
8774 Returns the modified Bessel function of the second kind for integer order
8775 `n` at real `z`.
8777 These are also sometimes called functions of the third kind, Basset
8778 functions, or Macdonald functions.
8780 Parameters
8781 ----------
8782 n : array_like of int
8783 Order of Bessel functions (floats will truncate with a warning)
8784 x : array_like of float
8785 Argument at which to evaluate the Bessel functions
8786 out : ndarray, optional
8787 Optional output array for the function results.
8789 Returns
8790 -------
8791 scalar or ndarray
8792 Value of the Modified Bessel function of the second kind,
8793 :math:`K_n(x)`.
8795 Notes
8796 -----
8797 Wrapper for AMOS [1]_ routine `zbesk`. For a discussion of the
8798 algorithm used, see [2]_ and the references therein.
8800 See Also
8801 --------
8802 kv : Same function, but accepts real order and complex argument
8803 kvp : Derivative of this function
8805 References
8806 ----------
8807 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
8808 of a Complex Argument and Nonnegative Order",
8809 http://netlib.org/amos/
8810 .. [2] Donald E. Amos, "Algorithm 644: A portable package for Bessel
8811 functions of a complex argument and nonnegative order", ACM
8812 TOMS Vol. 12 Issue 3, Sept. 1986, p. 265
8814 Examples
8815 --------
8816 Plot the function of several orders for real input:
8818 >>> import numpy as np
8819 >>> from scipy.special import kn
8820 >>> import matplotlib.pyplot as plt
8821 >>> x = np.linspace(0, 5, 1000)
8822 >>> for N in range(6):
8823 ... plt.plot(x, kn(N, x), label='$K_{}(x)$'.format(N))
8824 >>> plt.ylim(0, 10)
8825 >>> plt.legend()
8826 >>> plt.title(r'Modified Bessel function of the second kind $K_n(x)$')
8827 >>> plt.show()
8829 Calculate for a single value at multiple orders:
8831 >>> kn([4, 5, 6], 1)
8832 array([ 44.23241585, 360.9605896 , 3653.83831186])
8833 """)
8835add_newdoc("kolmogi",
8836 """
8837 kolmogi(p, out=None)
8839 Inverse Survival Function of Kolmogorov distribution
8841 It is the inverse function to `kolmogorov`.
8842 Returns y such that ``kolmogorov(y) == p``.
8844 Parameters
8845 ----------
8846 p : float array_like
8847 Probability
8848 out : ndarray, optional
8849 Optional output array for the function results
8851 Returns
8852 -------
8853 scalar or ndarray
8854 The value(s) of kolmogi(p)
8856 Notes
8857 -----
8858 `kolmogorov` is used by `stats.kstest` in the application of the
8859 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
8860 function is exposed in `scpy.special`, but the recommended way to achieve
8861 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
8862 `stats.kstwobign` distribution.
8864 See Also
8865 --------
8866 kolmogorov : The Survival Function for the distribution
8867 scipy.stats.kstwobign : Provides the functionality as a continuous distribution
8868 smirnov, smirnovi : Functions for the one-sided distribution
8870 Examples
8871 --------
8872 >>> from scipy.special import kolmogi
8873 >>> kolmogi([0, 0.1, 0.25, 0.5, 0.75, 0.9, 1.0])
8874 array([ inf, 1.22384787, 1.01918472, 0.82757356, 0.67644769,
8875 0.57117327, 0. ])
8877 """)
8879add_newdoc("kolmogorov",
8880 r"""
8881 kolmogorov(y, out=None)
8883 Complementary cumulative distribution (Survival Function) function of
8884 Kolmogorov distribution.
8886 Returns the complementary cumulative distribution function of
8887 Kolmogorov's limiting distribution (``D_n*\sqrt(n)`` as n goes to infinity)
8888 of a two-sided test for equality between an empirical and a theoretical
8889 distribution. It is equal to the (limit as n->infinity of the)
8890 probability that ``sqrt(n) * max absolute deviation > y``.
8892 Parameters
8893 ----------
8894 y : float array_like
8895 Absolute deviation between the Empirical CDF (ECDF) and the target CDF,
8896 multiplied by sqrt(n).
8897 out : ndarray, optional
8898 Optional output array for the function results
8900 Returns
8901 -------
8902 scalar or ndarray
8903 The value(s) of kolmogorov(y)
8905 Notes
8906 -----
8907 `kolmogorov` is used by `stats.kstest` in the application of the
8908 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
8909 function is exposed in `scpy.special`, but the recommended way to achieve
8910 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
8911 `stats.kstwobign` distribution.
8913 See Also
8914 --------
8915 kolmogi : The Inverse Survival Function for the distribution
8916 scipy.stats.kstwobign : Provides the functionality as a continuous distribution
8917 smirnov, smirnovi : Functions for the one-sided distribution
8919 Examples
8920 --------
8921 Show the probability of a gap at least as big as 0, 0.5 and 1.0.
8923 >>> import numpy as np
8924 >>> from scipy.special import kolmogorov
8925 >>> from scipy.stats import kstwobign
8926 >>> kolmogorov([0, 0.5, 1.0])
8927 array([ 1. , 0.96394524, 0.26999967])
8929 Compare a sample of size 1000 drawn from a Laplace(0, 1) distribution against
8930 the target distribution, a Normal(0, 1) distribution.
8932 >>> from scipy.stats import norm, laplace
8933 >>> rng = np.random.default_rng()
8934 >>> n = 1000
8935 >>> lap01 = laplace(0, 1)
8936 >>> x = np.sort(lap01.rvs(n, random_state=rng))
8937 >>> np.mean(x), np.std(x)
8938 (-0.05841730131499543, 1.3968109101997568)
8940 Construct the Empirical CDF and the K-S statistic Dn.
8942 >>> target = norm(0,1) # Normal mean 0, stddev 1
8943 >>> cdfs = target.cdf(x)
8944 >>> ecdfs = np.arange(n+1, dtype=float)/n
8945 >>> gaps = np.column_stack([cdfs - ecdfs[:n], ecdfs[1:] - cdfs])
8946 >>> Dn = np.max(gaps)
8947 >>> Kn = np.sqrt(n) * Dn
8948 >>> print('Dn=%f, sqrt(n)*Dn=%f' % (Dn, Kn))
8949 Dn=0.043363, sqrt(n)*Dn=1.371265
8950 >>> print(chr(10).join(['For a sample of size n drawn from a N(0, 1) distribution:',
8951 ... ' the approximate Kolmogorov probability that sqrt(n)*Dn>=%f is %f' % (Kn, kolmogorov(Kn)),
8952 ... ' the approximate Kolmogorov probability that sqrt(n)*Dn<=%f is %f' % (Kn, kstwobign.cdf(Kn))]))
8953 For a sample of size n drawn from a N(0, 1) distribution:
8954 the approximate Kolmogorov probability that sqrt(n)*Dn>=1.371265 is 0.046533
8955 the approximate Kolmogorov probability that sqrt(n)*Dn<=1.371265 is 0.953467
8957 Plot the Empirical CDF against the target N(0, 1) CDF.
8959 >>> import matplotlib.pyplot as plt
8960 >>> plt.step(np.concatenate([[-3], x]), ecdfs, where='post', label='Empirical CDF')
8961 >>> x3 = np.linspace(-3, 3, 100)
8962 >>> plt.plot(x3, target.cdf(x3), label='CDF for N(0, 1)')
8963 >>> plt.ylim([0, 1]); plt.grid(True); plt.legend();
8964 >>> # Add vertical lines marking Dn+ and Dn-
8965 >>> iminus, iplus = np.argmax(gaps, axis=0)
8966 >>> plt.vlines([x[iminus]], ecdfs[iminus], cdfs[iminus], color='r', linestyle='dashed', lw=4)
8967 >>> plt.vlines([x[iplus]], cdfs[iplus], ecdfs[iplus+1], color='r', linestyle='dashed', lw=4)
8968 >>> plt.show()
8969 """)
8971add_newdoc("_kolmogc",
8972 r"""
8973 Internal function, do not use.
8974 """)
8976add_newdoc("_kolmogci",
8977 r"""
8978 Internal function, do not use.
8979 """)
8981add_newdoc("_kolmogp",
8982 r"""
8983 Internal function, do not use.
8984 """)
8986add_newdoc("kv",
8987 r"""
8988 kv(v, z, out=None)
8990 Modified Bessel function of the second kind of real order `v`
8992 Returns the modified Bessel function of the second kind for real order
8993 `v` at complex `z`.
8995 These are also sometimes called functions of the third kind, Basset
8996 functions, or Macdonald functions. They are defined as those solutions
8997 of the modified Bessel equation for which,
8999 .. math::
9000 K_v(x) \sim \sqrt{\pi/(2x)} \exp(-x)
9002 as :math:`x \to \infty` [3]_.
9004 Parameters
9005 ----------
9006 v : array_like of float
9007 Order of Bessel functions
9008 z : array_like of complex
9009 Argument at which to evaluate the Bessel functions
9010 out : ndarray, optional
9011 Optional output array for the function results
9013 Returns
9014 -------
9015 scalar or ndarray
9016 The results. Note that input must be of complex type to get complex
9017 output, e.g. ``kv(3, -2+0j)`` instead of ``kv(3, -2)``.
9019 Notes
9020 -----
9021 Wrapper for AMOS [1]_ routine `zbesk`. For a discussion of the
9022 algorithm used, see [2]_ and the references therein.
9024 See Also
9025 --------
9026 kve : This function with leading exponential behavior stripped off.
9027 kvp : Derivative of this function
9029 References
9030 ----------
9031 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
9032 of a Complex Argument and Nonnegative Order",
9033 http://netlib.org/amos/
9034 .. [2] Donald E. Amos, "Algorithm 644: A portable package for Bessel
9035 functions of a complex argument and nonnegative order", ACM
9036 TOMS Vol. 12 Issue 3, Sept. 1986, p. 265
9037 .. [3] NIST Digital Library of Mathematical Functions,
9038 Eq. 10.25.E3. https://dlmf.nist.gov/10.25.E3
9040 Examples
9041 --------
9042 Plot the function of several orders for real input:
9044 >>> import numpy as np
9045 >>> from scipy.special import kv
9046 >>> import matplotlib.pyplot as plt
9047 >>> x = np.linspace(0, 5, 1000)
9048 >>> for N in np.linspace(0, 6, 5):
9049 ... plt.plot(x, kv(N, x), label='$K_{{{}}}(x)$'.format(N))
9050 >>> plt.ylim(0, 10)
9051 >>> plt.legend()
9052 >>> plt.title(r'Modified Bessel function of the second kind $K_\nu(x)$')
9053 >>> plt.show()
9055 Calculate for a single value at multiple orders:
9057 >>> kv([4, 4.5, 5], 1+2j)
9058 array([ 0.1992+2.3892j, 2.3493+3.6j , 7.2827+3.8104j])
9060 """)
9062add_newdoc("kve",
9063 r"""
9064 kve(v, z, out=None)
9066 Exponentially scaled modified Bessel function of the second kind.
9068 Returns the exponentially scaled, modified Bessel function of the
9069 second kind (sometimes called the third kind) for real order `v` at
9070 complex `z`::
9072 kve(v, z) = kv(v, z) * exp(z)
9074 Parameters
9075 ----------
9076 v : array_like of float
9077 Order of Bessel functions
9078 z : array_like of complex
9079 Argument at which to evaluate the Bessel functions
9080 out : ndarray, optional
9081 Optional output array for the function results
9083 Returns
9084 -------
9085 scalar or ndarray
9086 The exponentially scaled modified Bessel function of the second kind.
9088 Notes
9089 -----
9090 Wrapper for AMOS [1]_ routine `zbesk`. For a discussion of the
9091 algorithm used, see [2]_ and the references therein.
9093 See Also
9094 --------
9095 kv : This function without exponential scaling.
9096 k0e : Faster version of this function for order 0.
9097 k1e : Faster version of this function for order 1.
9099 References
9100 ----------
9101 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
9102 of a Complex Argument and Nonnegative Order",
9103 http://netlib.org/amos/
9104 .. [2] Donald E. Amos, "Algorithm 644: A portable package for Bessel
9105 functions of a complex argument and nonnegative order", ACM
9106 TOMS Vol. 12 Issue 3, Sept. 1986, p. 265
9108 Examples
9109 --------
9110 Evaluate the function of order 0 at one point.
9112 >>> import numpy as np
9113 >>> from scipy.special import kv, kve
9114 >>> import matplotlib.pyplot as plt
9115 >>> kve(0, 1.)
9116 1.1444630798068949
9118 Evaluate the function at one point for different orders by
9119 providing a list or NumPy array as argument for the `v` parameter:
9121 >>> kve([0, 1, 1.5], 1.)
9122 array([1.14446308, 1.63615349, 2.50662827])
9124 Evaluate the function at several points for order 0 by providing an
9125 array for `z`.
9127 >>> points = np.array([1., 3., 10.])
9128 >>> kve(0, points)
9129 array([1.14446308, 0.6977616 , 0.39163193])
9131 Evaluate the function at several points for different orders by
9132 providing arrays for both `v` for `z`. Both arrays have to be
9133 broadcastable to the correct shape. To calculate the orders 0, 1
9134 and 2 for a 1D array of points:
9136 >>> kve([[0], [1], [2]], points)
9137 array([[1.14446308, 0.6977616 , 0.39163193],
9138 [1.63615349, 0.80656348, 0.41076657],
9139 [4.41677005, 1.23547058, 0.47378525]])
9141 Plot the functions of order 0 to 3 from 0 to 5.
9143 >>> fig, ax = plt.subplots()
9144 >>> x = np.linspace(0., 5., 1000)
9145 >>> for i in range(4):
9146 ... ax.plot(x, kve(i, x), label=f'$K_{i!r}(z)\cdot e^z$')
9147 >>> ax.legend()
9148 >>> ax.set_xlabel(r"$z$")
9149 >>> ax.set_ylim(0, 4)
9150 >>> ax.set_xlim(0, 5)
9151 >>> plt.show()
9153 Exponentially scaled Bessel functions are useful for large arguments for
9154 which the unscaled Bessel functions over- or underflow. In the
9155 following example `kv` returns 0 whereas `kve` still returns
9156 a useful finite number.
9158 >>> kv(3, 1000.), kve(3, 1000.)
9159 (0.0, 0.03980696128440973)
9160 """)
9162add_newdoc("_lanczos_sum_expg_scaled",
9163 """
9164 Internal function, do not use.
9165 """)
9167add_newdoc("_lgam1p",
9168 """
9169 Internal function, do not use.
9170 """)
9172add_newdoc("log1p",
9173 """
9174 log1p(x, out=None)
9176 Calculates log(1 + x) for use when `x` is near zero.
9178 Parameters
9179 ----------
9180 x : array_like
9181 Real or complex valued input.
9182 out : ndarray, optional
9183 Optional output array for the function results.
9185 Returns
9186 -------
9187 scalar or ndarray
9188 Values of ``log(1 + x)``.
9190 See Also
9191 --------
9192 expm1, cosm1
9194 Examples
9195 --------
9196 >>> import numpy as np
9197 >>> import scipy.special as sc
9199 It is more accurate than using ``log(1 + x)`` directly for ``x``
9200 near 0. Note that in the below example ``1 + 1e-17 == 1`` to
9201 double precision.
9203 >>> sc.log1p(1e-17)
9204 1e-17
9205 >>> np.log(1 + 1e-17)
9206 0.0
9208 """)
9210add_newdoc("_log1pmx",
9211 """
9212 Internal function, do not use.
9213 """)
9215add_newdoc('log_expit',
9216 """
9217 log_expit(x, out=None)
9219 Logarithm of the logistic sigmoid function.
9221 The SciPy implementation of the logistic sigmoid function is
9222 `scipy.special.expit`, so this function is called ``log_expit``.
9224 The function is mathematically equivalent to ``log(expit(x))``, but
9225 is formulated to avoid loss of precision for inputs with large
9226 (positive or negative) magnitude.
9228 Parameters
9229 ----------
9230 x : array_like
9231 The values to apply ``log_expit`` to element-wise.
9232 out : ndarray, optional
9233 Optional output array for the function results
9235 Returns
9236 -------
9237 out : scalar or ndarray
9238 The computed values, an ndarray of the same shape as ``x``.
9240 See Also
9241 --------
9242 expit
9244 Notes
9245 -----
9246 As a ufunc, ``log_expit`` takes a number of optional keyword arguments.
9247 For more information see
9248 `ufuncs <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`_
9250 .. versionadded:: 1.8.0
9252 Examples
9253 --------
9254 >>> import numpy as np
9255 >>> from scipy.special import log_expit, expit
9257 >>> log_expit([-3.0, 0.25, 2.5, 5.0])
9258 array([-3.04858735, -0.57593942, -0.07888973, -0.00671535])
9260 Large negative values:
9262 >>> log_expit([-100, -500, -1000])
9263 array([ -100., -500., -1000.])
9265 Note that ``expit(-1000)`` returns 0, so the naive implementation
9266 ``log(expit(-1000))`` return ``-inf``.
9268 Large positive values:
9270 >>> log_expit([29, 120, 400])
9271 array([-2.54366565e-013, -7.66764807e-053, -1.91516960e-174])
9273 Compare that to the naive implementation:
9275 >>> np.log(expit([29, 120, 400]))
9276 array([-2.54463117e-13, 0.00000000e+00, 0.00000000e+00])
9278 The first value is accurate to only 3 digits, and the larger inputs
9279 lose all precision and return 0.
9280 """)
9282add_newdoc('logit',
9283 """
9284 logit(x, out=None)
9286 Logit ufunc for ndarrays.
9288 The logit function is defined as logit(p) = log(p/(1-p)).
9289 Note that logit(0) = -inf, logit(1) = inf, and logit(p)
9290 for p<0 or p>1 yields nan.
9292 Parameters
9293 ----------
9294 x : ndarray
9295 The ndarray to apply logit to element-wise.
9296 out : ndarray, optional
9297 Optional output array for the function results
9299 Returns
9300 -------
9301 scalar or ndarray
9302 An ndarray of the same shape as x. Its entries
9303 are logit of the corresponding entry of x.
9305 See Also
9306 --------
9307 expit
9309 Notes
9310 -----
9311 As a ufunc logit takes a number of optional
9312 keyword arguments. For more information
9313 see `ufuncs <https://docs.scipy.org/doc/numpy/reference/ufuncs.html>`_
9315 .. versionadded:: 0.10.0
9317 Examples
9318 --------
9319 >>> import numpy as np
9320 >>> from scipy.special import logit, expit
9322 >>> logit([0, 0.25, 0.5, 0.75, 1])
9323 array([ -inf, -1.09861229, 0. , 1.09861229, inf])
9325 `expit` is the inverse of `logit`:
9327 >>> expit(logit([0.1, 0.75, 0.999]))
9328 array([ 0.1 , 0.75 , 0.999])
9330 Plot logit(x) for x in [0, 1]:
9332 >>> import matplotlib.pyplot as plt
9333 >>> x = np.linspace(0, 1, 501)
9334 >>> y = logit(x)
9335 >>> plt.plot(x, y)
9336 >>> plt.grid()
9337 >>> plt.ylim(-6, 6)
9338 >>> plt.xlabel('x')
9339 >>> plt.title('logit(x)')
9340 >>> plt.show()
9342 """)
9344add_newdoc("lpmv",
9345 r"""
9346 lpmv(m, v, x, out=None)
9348 Associated Legendre function of integer order and real degree.
9350 Defined as
9352 .. math::
9354 P_v^m = (-1)^m (1 - x^2)^{m/2} \frac{d^m}{dx^m} P_v(x)
9356 where
9358 .. math::
9360 P_v = \sum_{k = 0}^\infty \frac{(-v)_k (v + 1)_k}{(k!)^2}
9361 \left(\frac{1 - x}{2}\right)^k
9363 is the Legendre function of the first kind. Here :math:`(\cdot)_k`
9364 is the Pochhammer symbol; see `poch`.
9366 Parameters
9367 ----------
9368 m : array_like
9369 Order (int or float). If passed a float not equal to an
9370 integer the function returns NaN.
9371 v : array_like
9372 Degree (float).
9373 x : array_like
9374 Argument (float). Must have ``|x| <= 1``.
9375 out : ndarray, optional
9376 Optional output array for the function results
9378 Returns
9379 -------
9380 pmv : scalar or ndarray
9381 Value of the associated Legendre function.
9383 See Also
9384 --------
9385 lpmn : Compute the associated Legendre function for all orders
9386 ``0, ..., m`` and degrees ``0, ..., n``.
9387 clpmn : Compute the associated Legendre function at complex
9388 arguments.
9390 Notes
9391 -----
9392 Note that this implementation includes the Condon-Shortley phase.
9394 References
9395 ----------
9396 .. [1] Zhang, Jin, "Computation of Special Functions", John Wiley
9397 and Sons, Inc, 1996.
9399 """)
9401add_newdoc("mathieu_a",
9402 """
9403 mathieu_a(m, q, out=None)
9405 Characteristic value of even Mathieu functions
9407 Parameters
9408 ----------
9409 m : array_like
9410 Order of the function
9411 q : array_like
9412 Parameter of the function
9413 out : ndarray, optional
9414 Optional output array for the function results
9416 Returns
9417 -------
9418 scalar or ndarray
9419 Characteristic value for the even solution, ``ce_m(z, q)``, of
9420 Mathieu's equation.
9422 See Also
9423 --------
9424 mathieu_b, mathieu_cem, mathieu_sem
9426 """)
9428add_newdoc("mathieu_b",
9429 """
9430 mathieu_b(m, q, out=None)
9432 Characteristic value of odd Mathieu functions
9434 Parameters
9435 ----------
9436 m : array_like
9437 Order of the function
9438 q : array_like
9439 Parameter of the function
9440 out : ndarray, optional
9441 Optional output array for the function results
9443 Returns
9444 -------
9445 scalar or ndarray
9446 Characteristic value for the odd solution, ``se_m(z, q)``, of Mathieu's
9447 equation.
9449 See Also
9450 --------
9451 mathieu_a, mathieu_cem, mathieu_sem
9453 """)
9455add_newdoc("mathieu_cem",
9456 """
9457 mathieu_cem(m, q, x, out=None)
9459 Even Mathieu function and its derivative
9461 Returns the even Mathieu function, ``ce_m(x, q)``, of order `m` and
9462 parameter `q` evaluated at `x` (given in degrees). Also returns the
9463 derivative with respect to `x` of ce_m(x, q)
9465 Parameters
9466 ----------
9467 m : array_like
9468 Order of the function
9469 q : array_like
9470 Parameter of the function
9471 x : array_like
9472 Argument of the function, *given in degrees, not radians*
9473 out : tuple of ndarray, optional
9474 Optional output arrays for the function results
9476 Returns
9477 -------
9478 y : scalar or ndarray
9479 Value of the function
9480 yp : scalar or ndarray
9481 Value of the derivative vs x
9483 See Also
9484 --------
9485 mathieu_a, mathieu_b, mathieu_sem
9487 """)
9489add_newdoc("mathieu_modcem1",
9490 """
9491 mathieu_modcem1(m, q, x, out=None)
9493 Even modified Mathieu function of the first kind and its derivative
9495 Evaluates the even modified Mathieu function of the first kind,
9496 ``Mc1m(x, q)``, and its derivative at `x` for order `m` and parameter
9497 `q`.
9499 Parameters
9500 ----------
9501 m : array_like
9502 Order of the function
9503 q : array_like
9504 Parameter of the function
9505 x : array_like
9506 Argument of the function, *given in degrees, not radians*
9507 out : tuple of ndarray, optional
9508 Optional output arrays for the function results
9510 Returns
9511 -------
9512 y : scalar or ndarray
9513 Value of the function
9514 yp : scalar or ndarray
9515 Value of the derivative vs x
9517 See Also
9518 --------
9519 mathieu_modsem1
9521 """)
9523add_newdoc("mathieu_modcem2",
9524 """
9525 mathieu_modcem2(m, q, x, out=None)
9527 Even modified Mathieu function of the second kind and its derivative
9529 Evaluates the even modified Mathieu function of the second kind,
9530 Mc2m(x, q), and its derivative at `x` (given in degrees) for order `m`
9531 and parameter `q`.
9533 Parameters
9534 ----------
9535 m : array_like
9536 Order of the function
9537 q : array_like
9538 Parameter of the function
9539 x : array_like
9540 Argument of the function, *given in degrees, not radians*
9541 out : tuple of ndarray, optional
9542 Optional output arrays for the function results
9544 Returns
9545 -------
9546 y : scalar or ndarray
9547 Value of the function
9548 yp : scalar or ndarray
9549 Value of the derivative vs x
9551 See Also
9552 --------
9553 mathieu_modsem2
9555 """)
9557add_newdoc("mathieu_modsem1",
9558 """
9559 mathieu_modsem1(m, q, x, out=None)
9561 Odd modified Mathieu function of the first kind and its derivative
9563 Evaluates the odd modified Mathieu function of the first kind,
9564 Ms1m(x, q), and its derivative at `x` (given in degrees) for order `m`
9565 and parameter `q`.
9567 Parameters
9568 ----------
9569 m : array_like
9570 Order of the function
9571 q : array_like
9572 Parameter of the function
9573 x : array_like
9574 Argument of the function, *given in degrees, not radians*
9575 out : tuple of ndarray, optional
9576 Optional output arrays for the function results
9578 Returns
9579 -------
9580 y : scalar or ndarray
9581 Value of the function
9582 yp : scalar or ndarray
9583 Value of the derivative vs x
9585 See Also
9586 --------
9587 mathieu_modcem1
9589 """)
9591add_newdoc("mathieu_modsem2",
9592 """
9593 mathieu_modsem2(m, q, x, out=None)
9595 Odd modified Mathieu function of the second kind and its derivative
9597 Evaluates the odd modified Mathieu function of the second kind,
9598 Ms2m(x, q), and its derivative at `x` (given in degrees) for order `m`
9599 and parameter q.
9601 Parameters
9602 ----------
9603 m : array_like
9604 Order of the function
9605 q : array_like
9606 Parameter of the function
9607 x : array_like
9608 Argument of the function, *given in degrees, not radians*
9609 out : tuple of ndarray, optional
9610 Optional output arrays for the function results
9612 Returns
9613 -------
9614 y : scalar or ndarray
9615 Value of the function
9616 yp : scalar or ndarray
9617 Value of the derivative vs x
9619 See Also
9620 --------
9621 mathieu_modcem2
9623 """)
9625add_newdoc(
9626 "mathieu_sem",
9627 """
9628 mathieu_sem(m, q, x, out=None)
9630 Odd Mathieu function and its derivative
9632 Returns the odd Mathieu function, se_m(x, q), of order `m` and
9633 parameter `q` evaluated at `x` (given in degrees). Also returns the
9634 derivative with respect to `x` of se_m(x, q).
9636 Parameters
9637 ----------
9638 m : array_like
9639 Order of the function
9640 q : array_like
9641 Parameter of the function
9642 x : array_like
9643 Argument of the function, *given in degrees, not radians*.
9644 out : tuple of ndarray, optional
9645 Optional output arrays for the function results
9647 Returns
9648 -------
9649 y : scalar or ndarray
9650 Value of the function
9651 yp : scalar or ndarray
9652 Value of the derivative vs x
9654 See Also
9655 --------
9656 mathieu_a, mathieu_b, mathieu_cem
9658 """)
9660add_newdoc("modfresnelm",
9661 """
9662 modfresnelm(x, out=None)
9664 Modified Fresnel negative integrals
9666 Parameters
9667 ----------
9668 x : array_like
9669 Function argument
9670 out : tuple of ndarray, optional
9671 Optional output arrays for the function results
9673 Returns
9674 -------
9675 fm : scalar or ndarray
9676 Integral ``F_-(x)``: ``integral(exp(-1j*t*t), t=x..inf)``
9677 km : scalar or ndarray
9678 Integral ``K_-(x)``: ``1/sqrt(pi)*exp(1j*(x*x+pi/4))*fp``
9680 See Also
9681 --------
9682 modfresnelp
9684 """)
9686add_newdoc("modfresnelp",
9687 """
9688 modfresnelp(x, out=None)
9690 Modified Fresnel positive integrals
9692 Parameters
9693 ----------
9694 x : array_like
9695 Function argument
9696 out : tuple of ndarray, optional
9697 Optional output arrays for the function results
9699 Returns
9700 -------
9701 fp : scalar or ndarray
9702 Integral ``F_+(x)``: ``integral(exp(1j*t*t), t=x..inf)``
9703 kp : scalar or ndarray
9704 Integral ``K_+(x)``: ``1/sqrt(pi)*exp(-1j*(x*x+pi/4))*fp``
9706 See Also
9707 --------
9708 modfresnelm
9710 """)
9712add_newdoc("modstruve",
9713 r"""
9714 modstruve(v, x, out=None)
9716 Modified Struve function.
9718 Return the value of the modified Struve function of order `v` at `x`. The
9719 modified Struve function is defined as,
9721 .. math::
9722 L_v(x) = -\imath \exp(-\pi\imath v/2) H_v(\imath x),
9724 where :math:`H_v` is the Struve function.
9726 Parameters
9727 ----------
9728 v : array_like
9729 Order of the modified Struve function (float).
9730 x : array_like
9731 Argument of the Struve function (float; must be positive unless `v` is
9732 an integer).
9733 out : ndarray, optional
9734 Optional output array for the function results
9736 Returns
9737 -------
9738 L : scalar or ndarray
9739 Value of the modified Struve function of order `v` at `x`.
9741 Notes
9742 -----
9743 Three methods discussed in [1]_ are used to evaluate the function:
9745 - power series
9746 - expansion in Bessel functions (if :math:`|x| < |v| + 20`)
9747 - asymptotic large-x expansion (if :math:`x \geq 0.7v + 12`)
9749 Rounding errors are estimated based on the largest terms in the sums, and
9750 the result associated with the smallest error is returned.
9752 See also
9753 --------
9754 struve
9756 References
9757 ----------
9758 .. [1] NIST Digital Library of Mathematical Functions
9759 https://dlmf.nist.gov/11
9761 Examples
9762 --------
9763 Calculate the modified Struve function of order 1 at 2.
9765 >>> import numpy as np
9766 >>> from scipy.special import modstruve
9767 >>> import matplotlib.pyplot as plt
9768 >>> modstruve(1, 2.)
9769 1.102759787367716
9771 Calculate the modified Struve function at 2 for orders 1, 2 and 3 by
9772 providing a list for the order parameter `v`.
9774 >>> modstruve([1, 2, 3], 2.)
9775 array([1.10275979, 0.41026079, 0.11247294])
9777 Calculate the modified Struve function of order 1 for several points
9778 by providing an array for `x`.
9780 >>> points = np.array([2., 5., 8.])
9781 >>> modstruve(1, points)
9782 array([ 1.10275979, 23.72821578, 399.24709139])
9784 Compute the modified Struve function for several orders at several
9785 points by providing arrays for `v` and `z`. The arrays have to be
9786 broadcastable to the correct shapes.
9788 >>> orders = np.array([[1], [2], [3]])
9789 >>> points.shape, orders.shape
9790 ((3,), (3, 1))
9792 >>> modstruve(orders, points)
9793 array([[1.10275979e+00, 2.37282158e+01, 3.99247091e+02],
9794 [4.10260789e-01, 1.65535979e+01, 3.25973609e+02],
9795 [1.12472937e-01, 9.42430454e+00, 2.33544042e+02]])
9797 Plot the modified Struve functions of order 0 to 3 from -5 to 5.
9799 >>> fig, ax = plt.subplots()
9800 >>> x = np.linspace(-5., 5., 1000)
9801 >>> for i in range(4):
9802 ... ax.plot(x, modstruve(i, x), label=f'$L_{i!r}$')
9803 >>> ax.legend(ncol=2)
9804 >>> ax.set_xlim(-5, 5)
9805 >>> ax.set_title(r"Modified Struve functions $L_{\nu}$")
9806 >>> plt.show()
9807 """)
9809add_newdoc("nbdtr",
9810 r"""
9811 nbdtr(k, n, p, out=None)
9813 Negative binomial cumulative distribution function.
9815 Returns the sum of the terms 0 through `k` of the negative binomial
9816 distribution probability mass function,
9818 .. math::
9820 F = \sum_{j=0}^k {{n + j - 1}\choose{j}} p^n (1 - p)^j.
9822 In a sequence of Bernoulli trials with individual success probabilities
9823 `p`, this is the probability that `k` or fewer failures precede the nth
9824 success.
9826 Parameters
9827 ----------
9828 k : array_like
9829 The maximum number of allowed failures (nonnegative int).
9830 n : array_like
9831 The target number of successes (positive int).
9832 p : array_like
9833 Probability of success in a single event (float).
9834 out : ndarray, optional
9835 Optional output array for the function results
9837 Returns
9838 -------
9839 F : scalar or ndarray
9840 The probability of `k` or fewer failures before `n` successes in a
9841 sequence of events with individual success probability `p`.
9843 See also
9844 --------
9845 nbdtrc
9847 Notes
9848 -----
9849 If floating point values are passed for `k` or `n`, they will be truncated
9850 to integers.
9852 The terms are not summed directly; instead the regularized incomplete beta
9853 function is employed, according to the formula,
9855 .. math::
9856 \mathrm{nbdtr}(k, n, p) = I_{p}(n, k + 1).
9858 Wrapper for the Cephes [1]_ routine `nbdtr`.
9860 References
9861 ----------
9862 .. [1] Cephes Mathematical Functions Library,
9863 http://www.netlib.org/cephes/
9865 """)
9867add_newdoc("nbdtrc",
9868 r"""
9869 nbdtrc(k, n, p, out=None)
9871 Negative binomial survival function.
9873 Returns the sum of the terms `k + 1` to infinity of the negative binomial
9874 distribution probability mass function,
9876 .. math::
9878 F = \sum_{j=k + 1}^\infty {{n + j - 1}\choose{j}} p^n (1 - p)^j.
9880 In a sequence of Bernoulli trials with individual success probabilities
9881 `p`, this is the probability that more than `k` failures precede the nth
9882 success.
9884 Parameters
9885 ----------
9886 k : array_like
9887 The maximum number of allowed failures (nonnegative int).
9888 n : array_like
9889 The target number of successes (positive int).
9890 p : array_like
9891 Probability of success in a single event (float).
9892 out : ndarray, optional
9893 Optional output array for the function results
9895 Returns
9896 -------
9897 F : scalar or ndarray
9898 The probability of `k + 1` or more failures before `n` successes in a
9899 sequence of events with individual success probability `p`.
9901 Notes
9902 -----
9903 If floating point values are passed for `k` or `n`, they will be truncated
9904 to integers.
9906 The terms are not summed directly; instead the regularized incomplete beta
9907 function is employed, according to the formula,
9909 .. math::
9910 \mathrm{nbdtrc}(k, n, p) = I_{1 - p}(k + 1, n).
9912 Wrapper for the Cephes [1]_ routine `nbdtrc`.
9914 References
9915 ----------
9916 .. [1] Cephes Mathematical Functions Library,
9917 http://www.netlib.org/cephes/
9918 """)
9920add_newdoc("nbdtri",
9921 """
9922 nbdtri(k, n, y, out=None)
9924 Inverse of `nbdtr` vs `p`.
9926 Returns the inverse with respect to the parameter `p` of
9927 `y = nbdtr(k, n, p)`, the negative binomial cumulative distribution
9928 function.
9930 Parameters
9931 ----------
9932 k : array_like
9933 The maximum number of allowed failures (nonnegative int).
9934 n : array_like
9935 The target number of successes (positive int).
9936 y : array_like
9937 The probability of `k` or fewer failures before `n` successes (float).
9938 out : ndarray, optional
9939 Optional output array for the function results
9941 Returns
9942 -------
9943 p : scalar or ndarray
9944 Probability of success in a single event (float) such that
9945 `nbdtr(k, n, p) = y`.
9947 See also
9948 --------
9949 nbdtr : Cumulative distribution function of the negative binomial.
9950 nbdtrik : Inverse with respect to `k` of `nbdtr(k, n, p)`.
9951 nbdtrin : Inverse with respect to `n` of `nbdtr(k, n, p)`.
9953 Notes
9954 -----
9955 Wrapper for the Cephes [1]_ routine `nbdtri`.
9957 References
9958 ----------
9959 .. [1] Cephes Mathematical Functions Library,
9960 http://www.netlib.org/cephes/
9962 """)
9964add_newdoc("nbdtrik",
9965 r"""
9966 nbdtrik(y, n, p, out=None)
9968 Inverse of `nbdtr` vs `k`.
9970 Returns the inverse with respect to the parameter `k` of
9971 `y = nbdtr(k, n, p)`, the negative binomial cumulative distribution
9972 function.
9974 Parameters
9975 ----------
9976 y : array_like
9977 The probability of `k` or fewer failures before `n` successes (float).
9978 n : array_like
9979 The target number of successes (positive int).
9980 p : array_like
9981 Probability of success in a single event (float).
9982 out : ndarray, optional
9983 Optional output array for the function results
9985 Returns
9986 -------
9987 k : scalar or ndarray
9988 The maximum number of allowed failures such that `nbdtr(k, n, p) = y`.
9990 See also
9991 --------
9992 nbdtr : Cumulative distribution function of the negative binomial.
9993 nbdtri : Inverse with respect to `p` of `nbdtr(k, n, p)`.
9994 nbdtrin : Inverse with respect to `n` of `nbdtr(k, n, p)`.
9996 Notes
9997 -----
9998 Wrapper for the CDFLIB [1]_ Fortran routine `cdfnbn`.
10000 Formula 26.5.26 of [2]_,
10002 .. math::
10003 \sum_{j=k + 1}^\infty {{n + j - 1}\choose{j}} p^n (1 - p)^j = I_{1 - p}(k + 1, n),
10005 is used to reduce calculation of the cumulative distribution function to
10006 that of a regularized incomplete beta :math:`I`.
10008 Computation of `k` involves a search for a value that produces the desired
10009 value of `y`. The search relies on the monotonicity of `y` with `k`.
10011 References
10012 ----------
10013 .. [1] Barry Brown, James Lovato, and Kathy Russell,
10014 CDFLIB: Library of Fortran Routines for Cumulative Distribution
10015 Functions, Inverses, and Other Parameters.
10016 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
10017 Handbook of Mathematical Functions with Formulas,
10018 Graphs, and Mathematical Tables. New York: Dover, 1972.
10020 """)
10022add_newdoc("nbdtrin",
10023 r"""
10024 nbdtrin(k, y, p, out=None)
10026 Inverse of `nbdtr` vs `n`.
10028 Returns the inverse with respect to the parameter `n` of
10029 `y = nbdtr(k, n, p)`, the negative binomial cumulative distribution
10030 function.
10032 Parameters
10033 ----------
10034 k : array_like
10035 The maximum number of allowed failures (nonnegative int).
10036 y : array_like
10037 The probability of `k` or fewer failures before `n` successes (float).
10038 p : array_like
10039 Probability of success in a single event (float).
10040 out : ndarray, optional
10041 Optional output array for the function results
10043 Returns
10044 -------
10045 n : scalar or ndarray
10046 The number of successes `n` such that `nbdtr(k, n, p) = y`.
10048 See also
10049 --------
10050 nbdtr : Cumulative distribution function of the negative binomial.
10051 nbdtri : Inverse with respect to `p` of `nbdtr(k, n, p)`.
10052 nbdtrik : Inverse with respect to `k` of `nbdtr(k, n, p)`.
10054 Notes
10055 -----
10056 Wrapper for the CDFLIB [1]_ Fortran routine `cdfnbn`.
10058 Formula 26.5.26 of [2]_,
10060 .. math::
10061 \sum_{j=k + 1}^\infty {{n + j - 1}\choose{j}} p^n (1 - p)^j = I_{1 - p}(k + 1, n),
10063 is used to reduce calculation of the cumulative distribution function to
10064 that of a regularized incomplete beta :math:`I`.
10066 Computation of `n` involves a search for a value that produces the desired
10067 value of `y`. The search relies on the monotonicity of `y` with `n`.
10069 References
10070 ----------
10071 .. [1] Barry Brown, James Lovato, and Kathy Russell,
10072 CDFLIB: Library of Fortran Routines for Cumulative Distribution
10073 Functions, Inverses, and Other Parameters.
10074 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
10075 Handbook of Mathematical Functions with Formulas,
10076 Graphs, and Mathematical Tables. New York: Dover, 1972.
10078 """)
10080add_newdoc("ncfdtr",
10081 r"""
10082 ncfdtr(dfn, dfd, nc, f, out=None)
10084 Cumulative distribution function of the non-central F distribution.
10086 The non-central F describes the distribution of,
10088 .. math::
10089 Z = \frac{X/d_n}{Y/d_d}
10091 where :math:`X` and :math:`Y` are independently distributed, with
10092 :math:`X` distributed non-central :math:`\chi^2` with noncentrality
10093 parameter `nc` and :math:`d_n` degrees of freedom, and :math:`Y`
10094 distributed :math:`\chi^2` with :math:`d_d` degrees of freedom.
10096 Parameters
10097 ----------
10098 dfn : array_like
10099 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10100 dfd : array_like
10101 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10102 nc : array_like
10103 Noncentrality parameter. Should be in range (0, 1e4).
10104 f : array_like
10105 Quantiles, i.e. the upper limit of integration.
10106 out : ndarray, optional
10107 Optional output array for the function results
10109 Returns
10110 -------
10111 cdf : scalar or ndarray
10112 The calculated CDF. If all inputs are scalar, the return will be a
10113 float. Otherwise it will be an array.
10115 See Also
10116 --------
10117 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10118 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10119 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10120 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10122 Notes
10123 -----
10124 Wrapper for the CDFLIB [1]_ Fortran routine `cdffnc`.
10126 The cumulative distribution function is computed using Formula 26.6.20 of
10127 [2]_:
10129 .. math::
10130 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}),
10132 where :math:`I` is the regularized incomplete beta function, and
10133 :math:`x = f d_n/(f d_n + d_d)`.
10135 The computation time required for this routine is proportional to the
10136 noncentrality parameter `nc`. Very large values of this parameter can
10137 consume immense computer resources. This is why the search range is
10138 bounded by 10,000.
10140 References
10141 ----------
10142 .. [1] Barry Brown, James Lovato, and Kathy Russell,
10143 CDFLIB: Library of Fortran Routines for Cumulative Distribution
10144 Functions, Inverses, and Other Parameters.
10145 .. [2] Milton Abramowitz and Irene A. Stegun, eds.
10146 Handbook of Mathematical Functions with Formulas,
10147 Graphs, and Mathematical Tables. New York: Dover, 1972.
10149 Examples
10150 --------
10151 >>> import numpy as np
10152 >>> from scipy import special
10153 >>> from scipy import stats
10154 >>> import matplotlib.pyplot as plt
10156 Plot the CDF of the non-central F distribution, for nc=0. Compare with the
10157 F-distribution from scipy.stats:
10159 >>> x = np.linspace(-1, 8, num=500)
10160 >>> dfn = 3
10161 >>> dfd = 2
10162 >>> ncf_stats = stats.f.cdf(x, dfn, dfd)
10163 >>> ncf_special = special.ncfdtr(dfn, dfd, 0, x)
10165 >>> fig = plt.figure()
10166 >>> ax = fig.add_subplot(111)
10167 >>> ax.plot(x, ncf_stats, 'b-', lw=3)
10168 >>> ax.plot(x, ncf_special, 'r-')
10169 >>> plt.show()
10171 """)
10173add_newdoc("ncfdtri",
10174 """
10175 ncfdtri(dfn, dfd, nc, p, out=None)
10177 Inverse with respect to `f` of the CDF of the non-central F distribution.
10179 See `ncfdtr` for more details.
10181 Parameters
10182 ----------
10183 dfn : array_like
10184 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10185 dfd : array_like
10186 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10187 nc : array_like
10188 Noncentrality parameter. Should be in range (0, 1e4).
10189 p : array_like
10190 Value of the cumulative distribution function. Must be in the
10191 range [0, 1].
10192 out : ndarray, optional
10193 Optional output array for the function results
10195 Returns
10196 -------
10197 f : scalar or ndarray
10198 Quantiles, i.e., the upper limit of integration.
10200 See Also
10201 --------
10202 ncfdtr : CDF of the non-central F distribution.
10203 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10204 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10205 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10207 Examples
10208 --------
10209 >>> from scipy.special import ncfdtr, ncfdtri
10211 Compute the CDF for several values of `f`:
10213 >>> f = [0.5, 1, 1.5]
10214 >>> p = ncfdtr(2, 3, 1.5, f)
10215 >>> p
10216 array([ 0.20782291, 0.36107392, 0.47345752])
10218 Compute the inverse. We recover the values of `f`, as expected:
10220 >>> ncfdtri(2, 3, 1.5, p)
10221 array([ 0.5, 1. , 1.5])
10223 """)
10225add_newdoc("ncfdtridfd",
10226 """
10227 ncfdtridfd(dfn, p, nc, f, out=None)
10229 Calculate degrees of freedom (denominator) for the noncentral F-distribution.
10231 This is the inverse with respect to `dfd` of `ncfdtr`.
10232 See `ncfdtr` for more details.
10234 Parameters
10235 ----------
10236 dfn : array_like
10237 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10238 p : array_like
10239 Value of the cumulative distribution function. Must be in the
10240 range [0, 1].
10241 nc : array_like
10242 Noncentrality parameter. Should be in range (0, 1e4).
10243 f : array_like
10244 Quantiles, i.e., the upper limit of integration.
10245 out : ndarray, optional
10246 Optional output array for the function results
10248 Returns
10249 -------
10250 dfd : scalar or ndarray
10251 Degrees of freedom of the denominator sum of squares.
10253 See Also
10254 --------
10255 ncfdtr : CDF of the non-central F distribution.
10256 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10257 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10258 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10260 Notes
10261 -----
10262 The value of the cumulative noncentral F distribution is not necessarily
10263 monotone in either degrees of freedom. There thus may be two values that
10264 provide a given CDF value. This routine assumes monotonicity and will
10265 find an arbitrary one of the two values.
10267 Examples
10268 --------
10269 >>> from scipy.special import ncfdtr, ncfdtridfd
10271 Compute the CDF for several values of `dfd`:
10273 >>> dfd = [1, 2, 3]
10274 >>> p = ncfdtr(2, dfd, 0.25, 15)
10275 >>> p
10276 array([ 0.8097138 , 0.93020416, 0.96787852])
10278 Compute the inverse. We recover the values of `dfd`, as expected:
10280 >>> ncfdtridfd(2, p, 0.25, 15)
10281 array([ 1., 2., 3.])
10283 """)
10285add_newdoc("ncfdtridfn",
10286 """
10287 ncfdtridfn(p, dfd, nc, f, out=None)
10289 Calculate degrees of freedom (numerator) for the noncentral F-distribution.
10291 This is the inverse with respect to `dfn` of `ncfdtr`.
10292 See `ncfdtr` for more details.
10294 Parameters
10295 ----------
10296 p : array_like
10297 Value of the cumulative distribution function. Must be in the
10298 range [0, 1].
10299 dfd : array_like
10300 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10301 nc : array_like
10302 Noncentrality parameter. Should be in range (0, 1e4).
10303 f : float
10304 Quantiles, i.e., the upper limit of integration.
10305 out : ndarray, optional
10306 Optional output array for the function results
10308 Returns
10309 -------
10310 dfn : scalar or ndarray
10311 Degrees of freedom of the numerator sum of squares.
10313 See Also
10314 --------
10315 ncfdtr : CDF of the non-central F distribution.
10316 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10317 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10318 ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.
10320 Notes
10321 -----
10322 The value of the cumulative noncentral F distribution is not necessarily
10323 monotone in either degrees of freedom. There thus may be two values that
10324 provide a given CDF value. This routine assumes monotonicity and will
10325 find an arbitrary one of the two values.
10327 Examples
10328 --------
10329 >>> from scipy.special import ncfdtr, ncfdtridfn
10331 Compute the CDF for several values of `dfn`:
10333 >>> dfn = [1, 2, 3]
10334 >>> p = ncfdtr(dfn, 2, 0.25, 15)
10335 >>> p
10336 array([ 0.92562363, 0.93020416, 0.93188394])
10338 Compute the inverse. We recover the values of `dfn`, as expected:
10340 >>> ncfdtridfn(p, 2, 0.25, 15)
10341 array([ 1., 2., 3.])
10343 """)
10345add_newdoc("ncfdtrinc",
10346 """
10347 ncfdtrinc(dfn, dfd, p, f, out=None)
10349 Calculate non-centrality parameter for non-central F distribution.
10351 This is the inverse with respect to `nc` of `ncfdtr`.
10352 See `ncfdtr` for more details.
10354 Parameters
10355 ----------
10356 dfn : array_like
10357 Degrees of freedom of the numerator sum of squares. Range (0, inf).
10358 dfd : array_like
10359 Degrees of freedom of the denominator sum of squares. Range (0, inf).
10360 p : array_like
10361 Value of the cumulative distribution function. Must be in the
10362 range [0, 1].
10363 f : array_like
10364 Quantiles, i.e., the upper limit of integration.
10365 out : ndarray, optional
10366 Optional output array for the function results
10368 Returns
10369 -------
10370 nc : scalar or ndarray
10371 Noncentrality parameter.
10373 See Also
10374 --------
10375 ncfdtr : CDF of the non-central F distribution.
10376 ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
10377 ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
10378 ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
10380 Examples
10381 --------
10382 >>> from scipy.special import ncfdtr, ncfdtrinc
10384 Compute the CDF for several values of `nc`:
10386 >>> nc = [0.5, 1.5, 2.0]
10387 >>> p = ncfdtr(2, 3, nc, 15)
10388 >>> p
10389 array([ 0.96309246, 0.94327955, 0.93304098])
10391 Compute the inverse. We recover the values of `nc`, as expected:
10393 >>> ncfdtrinc(2, 3, p, 15)
10394 array([ 0.5, 1.5, 2. ])
10396 """)
10398add_newdoc("nctdtr",
10399 """
10400 nctdtr(df, nc, t, out=None)
10402 Cumulative distribution function of the non-central `t` distribution.
10404 Parameters
10405 ----------
10406 df : array_like
10407 Degrees of freedom of the distribution. Should be in range (0, inf).
10408 nc : array_like
10409 Noncentrality parameter. Should be in range (-1e6, 1e6).
10410 t : array_like
10411 Quantiles, i.e., the upper limit of integration.
10412 out : ndarray, optional
10413 Optional output array for the function results
10415 Returns
10416 -------
10417 cdf : scalar or ndarray
10418 The calculated CDF. If all inputs are scalar, the return will be a
10419 float. Otherwise, it will be an array.
10421 See Also
10422 --------
10423 nctdtrit : Inverse CDF (iCDF) of the non-central t distribution.
10424 nctdtridf : Calculate degrees of freedom, given CDF and iCDF values.
10425 nctdtrinc : Calculate non-centrality parameter, given CDF iCDF values.
10427 Examples
10428 --------
10429 >>> import numpy as np
10430 >>> from scipy import special
10431 >>> from scipy import stats
10432 >>> import matplotlib.pyplot as plt
10434 Plot the CDF of the non-central t distribution, for nc=0. Compare with the
10435 t-distribution from scipy.stats:
10437 >>> x = np.linspace(-5, 5, num=500)
10438 >>> df = 3
10439 >>> nct_stats = stats.t.cdf(x, df)
10440 >>> nct_special = special.nctdtr(df, 0, x)
10442 >>> fig = plt.figure()
10443 >>> ax = fig.add_subplot(111)
10444 >>> ax.plot(x, nct_stats, 'b-', lw=3)
10445 >>> ax.plot(x, nct_special, 'r-')
10446 >>> plt.show()
10448 """)
10450add_newdoc("nctdtridf",
10451 """
10452 nctdtridf(p, nc, t, out=None)
10454 Calculate degrees of freedom for non-central t distribution.
10456 See `nctdtr` for more details.
10458 Parameters
10459 ----------
10460 p : array_like
10461 CDF values, in range (0, 1].
10462 nc : array_like
10463 Noncentrality parameter. Should be in range (-1e6, 1e6).
10464 t : array_like
10465 Quantiles, i.e., the upper limit of integration.
10466 out : ndarray, optional
10467 Optional output array for the function results
10469 Returns
10470 -------
10471 cdf : scalar or ndarray
10472 The calculated CDF. If all inputs are scalar, the return will be a
10473 float. Otherwise, it will be an array.
10475 See Also
10476 --------
10477 nctdtr : CDF of the non-central `t` distribution.
10478 nctdtrit : Inverse CDF (iCDF) of the non-central t distribution.
10479 nctdtrinc : Calculate non-centrality parameter, given CDF iCDF values.
10481 """)
10483add_newdoc("nctdtrinc",
10484 """
10485 nctdtrinc(df, p, t, out=None)
10487 Calculate non-centrality parameter for non-central t distribution.
10489 See `nctdtr` for more details.
10491 Parameters
10492 ----------
10493 df : array_like
10494 Degrees of freedom of the distribution. Should be in range (0, inf).
10495 p : array_like
10496 CDF values, in range (0, 1].
10497 t : array_like
10498 Quantiles, i.e., the upper limit of integration.
10499 out : ndarray, optional
10500 Optional output array for the function results
10502 Returns
10503 -------
10504 nc : scalar or ndarray
10505 Noncentrality parameter
10507 See Also
10508 --------
10509 nctdtr : CDF of the non-central `t` distribution.
10510 nctdtrit : Inverse CDF (iCDF) of the non-central t distribution.
10511 nctdtridf : Calculate degrees of freedom, given CDF and iCDF values.
10513 """)
10515add_newdoc("nctdtrit",
10516 """
10517 nctdtrit(df, nc, p, out=None)
10519 Inverse cumulative distribution function of the non-central t distribution.
10521 See `nctdtr` for more details.
10523 Parameters
10524 ----------
10525 df : array_like
10526 Degrees of freedom of the distribution. Should be in range (0, inf).
10527 nc : array_like
10528 Noncentrality parameter. Should be in range (-1e6, 1e6).
10529 p : array_like
10530 CDF values, in range (0, 1].
10531 out : ndarray, optional
10532 Optional output array for the function results
10534 Returns
10535 -------
10536 t : scalar or ndarray
10537 Quantiles
10539 See Also
10540 --------
10541 nctdtr : CDF of the non-central `t` distribution.
10542 nctdtridf : Calculate degrees of freedom, given CDF and iCDF values.
10543 nctdtrinc : Calculate non-centrality parameter, given CDF iCDF values.
10545 """)
10547add_newdoc("ndtr",
10548 r"""
10549 ndtr(x, out=None)
10551 Gaussian cumulative distribution function.
10553 Returns the area under the standard Gaussian probability
10554 density function, integrated from minus infinity to `x`
10556 .. math::
10558 \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x \exp(-t^2/2) dt
10560 Parameters
10561 ----------
10562 x : array_like, real or complex
10563 Argument
10564 out : ndarray, optional
10565 Optional output array for the function results
10567 Returns
10568 -------
10569 scalar or ndarray
10570 The value of the normal CDF evaluated at `x`
10572 See Also
10573 --------
10574 erf, erfc, scipy.stats.norm, log_ndtr
10576 """)
10579add_newdoc("nrdtrimn",
10580 """
10581 nrdtrimn(p, x, std, out=None)
10583 Calculate mean of normal distribution given other params.
10585 Parameters
10586 ----------
10587 p : array_like
10588 CDF values, in range (0, 1].
10589 x : array_like
10590 Quantiles, i.e. the upper limit of integration.
10591 std : array_like
10592 Standard deviation.
10593 out : ndarray, optional
10594 Optional output array for the function results
10596 Returns
10597 -------
10598 mn : scalar or ndarray
10599 The mean of the normal distribution.
10601 See Also
10602 --------
10603 nrdtrimn, ndtr
10605 """)
10607add_newdoc("nrdtrisd",
10608 """
10609 nrdtrisd(p, x, mn, out=None)
10611 Calculate standard deviation of normal distribution given other params.
10613 Parameters
10614 ----------
10615 p : array_like
10616 CDF values, in range (0, 1].
10617 x : array_like
10618 Quantiles, i.e. the upper limit of integration.
10619 mn : scalar or ndarray
10620 The mean of the normal distribution.
10621 out : ndarray, optional
10622 Optional output array for the function results
10624 Returns
10625 -------
10626 std : scalar or ndarray
10627 Standard deviation.
10629 See Also
10630 --------
10631 ndtr
10633 """)
10635add_newdoc("log_ndtr",
10636 """
10637 log_ndtr(x, out=None)
10639 Logarithm of Gaussian cumulative distribution function.
10641 Returns the log of the area under the standard Gaussian probability
10642 density function, integrated from minus infinity to `x`::
10644 log(1/sqrt(2*pi) * integral(exp(-t**2 / 2), t=-inf..x))
10646 Parameters
10647 ----------
10648 x : array_like, real or complex
10649 Argument
10650 out : ndarray, optional
10651 Optional output array for the function results
10653 Returns
10654 -------
10655 scalar or ndarray
10656 The value of the log of the normal CDF evaluated at `x`
10658 See Also
10659 --------
10660 erf
10661 erfc
10662 scipy.stats.norm
10663 ndtr
10665 Examples
10666 --------
10667 >>> import numpy as np
10668 >>> from scipy.special import log_ndtr, ndtr
10670 The benefit of ``log_ndtr(x)`` over the naive implementation
10671 ``np.log(ndtr(x))`` is most evident with moderate to large positive
10672 values of ``x``:
10674 >>> x = np.array([6, 7, 9, 12, 15, 25])
10675 >>> log_ndtr(x)
10676 array([-9.86587646e-010, -1.27981254e-012, -1.12858841e-019,
10677 -1.77648211e-033, -3.67096620e-051, -3.05669671e-138])
10679 The results of the naive calculation for the moderate ``x`` values
10680 have only 5 or 6 correct significant digits. For values of ``x``
10681 greater than approximately 8.3, the naive expression returns 0:
10683 >>> np.log(ndtr(x))
10684 array([-9.86587701e-10, -1.27986510e-12, 0.00000000e+00,
10685 0.00000000e+00, 0.00000000e+00, 0.00000000e+00])
10686 """)
10688add_newdoc("ndtri",
10689 """
10690 ndtri(y, out=None)
10692 Inverse of `ndtr` vs x
10694 Returns the argument x for which the area under the Gaussian
10695 probability density function (integrated from minus infinity to `x`)
10696 is equal to y.
10698 Parameters
10699 ----------
10700 p : array_like
10701 Probability
10702 out : ndarray, optional
10703 Optional output array for the function results
10705 Returns
10706 -------
10707 x : scalar or ndarray
10708 Value of x such that ``ndtr(x) == p``.
10710 See Also
10711 --------
10712 ndtr
10714 """)
10716add_newdoc("obl_ang1",
10717 """
10718 obl_ang1(m, n, c, x, out=None)
10720 Oblate spheroidal angular function of the first kind and its derivative
10722 Computes the oblate spheroidal angular function of the first kind
10723 and its derivative (with respect to `x`) for mode parameters m>=0
10724 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
10726 Parameters
10727 ----------
10728 m : array_like
10729 Mode parameter m (nonnegative)
10730 n : array_like
10731 Mode parameter n (>= m)
10732 c : array_like
10733 Spheroidal parameter
10734 x : array_like
10735 Parameter x (``|x| < 1.0``)
10736 out : ndarray, optional
10737 Optional output array for the function results
10739 Returns
10740 -------
10741 s : scalar or ndarray
10742 Value of the function
10743 sp : scalar or ndarray
10744 Value of the derivative vs x
10746 See Also
10747 --------
10748 obl_ang1_cv
10750 """)
10752add_newdoc("obl_ang1_cv",
10753 """
10754 obl_ang1_cv(m, n, c, cv, x, out=None)
10756 Oblate spheroidal angular function obl_ang1 for precomputed characteristic value
10758 Computes the oblate spheroidal angular function of the first kind
10759 and its derivative (with respect to `x`) for mode parameters m>=0
10760 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
10761 pre-computed characteristic value.
10763 Parameters
10764 ----------
10765 m : array_like
10766 Mode parameter m (nonnegative)
10767 n : array_like
10768 Mode parameter n (>= m)
10769 c : array_like
10770 Spheroidal parameter
10771 cv : array_like
10772 Characteristic value
10773 x : array_like
10774 Parameter x (``|x| < 1.0``)
10775 out : ndarray, optional
10776 Optional output array for the function results
10778 Returns
10779 -------
10780 s : scalar or ndarray
10781 Value of the function
10782 sp : scalar or ndarray
10783 Value of the derivative vs x
10785 See Also
10786 --------
10787 obl_ang1
10789 """)
10791add_newdoc("obl_cv",
10792 """
10793 obl_cv(m, n, c, out=None)
10795 Characteristic value of oblate spheroidal function
10797 Computes the characteristic value of oblate spheroidal wave
10798 functions of order `m`, `n` (n>=m) and spheroidal parameter `c`.
10800 Parameters
10801 ----------
10802 m : array_like
10803 Mode parameter m (nonnegative)
10804 n : array_like
10805 Mode parameter n (>= m)
10806 c : array_like
10807 Spheroidal parameter
10808 out : ndarray, optional
10809 Optional output array for the function results
10811 Returns
10812 -------
10813 cv : scalar or ndarray
10814 Characteristic value
10816 """)
10818add_newdoc("obl_rad1",
10819 """
10820 obl_rad1(m, n, c, x, out=None)
10822 Oblate spheroidal radial function of the first kind and its derivative
10824 Computes the oblate spheroidal radial function of the first kind
10825 and its derivative (with respect to `x`) for mode parameters m>=0
10826 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
10828 Parameters
10829 ----------
10830 m : array_like
10831 Mode parameter m (nonnegative)
10832 n : array_like
10833 Mode parameter n (>= m)
10834 c : array_like
10835 Spheroidal parameter
10836 x : array_like
10837 Parameter x (``|x| < 1.0``)
10838 out : ndarray, optional
10839 Optional output array for the function results
10841 Returns
10842 -------
10843 s : scalar or ndarray
10844 Value of the function
10845 sp : scalar or ndarray
10846 Value of the derivative vs x
10848 See Also
10849 --------
10850 obl_rad1_cv
10852 """)
10854add_newdoc("obl_rad1_cv",
10855 """
10856 obl_rad1_cv(m, n, c, cv, x, out=None)
10858 Oblate spheroidal radial function obl_rad1 for precomputed characteristic value
10860 Computes the oblate spheroidal radial function of the first kind
10861 and its derivative (with respect to `x`) for mode parameters m>=0
10862 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
10863 pre-computed characteristic value.
10865 Parameters
10866 ----------
10867 m : array_like
10868 Mode parameter m (nonnegative)
10869 n : array_like
10870 Mode parameter n (>= m)
10871 c : array_like
10872 Spheroidal parameter
10873 cv : array_like
10874 Characteristic value
10875 x : array_like
10876 Parameter x (``|x| < 1.0``)
10877 out : ndarray, optional
10878 Optional output array for the function results
10880 Returns
10881 -------
10882 s : scalar or ndarray
10883 Value of the function
10884 sp : scalar or ndarray
10885 Value of the derivative vs x
10887 See Also
10888 --------
10889 obl_rad1
10891 """)
10893add_newdoc("obl_rad2",
10894 """
10895 obl_rad2(m, n, c, x, out=None)
10897 Oblate spheroidal radial function of the second kind and its derivative.
10899 Computes the oblate spheroidal radial function of the second kind
10900 and its derivative (with respect to `x`) for mode parameters m>=0
10901 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
10903 Parameters
10904 ----------
10905 m : array_like
10906 Mode parameter m (nonnegative)
10907 n : array_like
10908 Mode parameter n (>= m)
10909 c : array_like
10910 Spheroidal parameter
10911 x : array_like
10912 Parameter x (``|x| < 1.0``)
10913 out : ndarray, optional
10914 Optional output array for the function results
10916 Returns
10917 -------
10918 s : scalar or ndarray
10919 Value of the function
10920 sp : scalar or ndarray
10921 Value of the derivative vs x
10923 See Also
10924 --------
10925 obl_rad2_cv
10927 """)
10929add_newdoc("obl_rad2_cv",
10930 """
10931 obl_rad2_cv(m, n, c, cv, x, out=None)
10933 Oblate spheroidal radial function obl_rad2 for precomputed characteristic value
10935 Computes the oblate spheroidal radial function of the second kind
10936 and its derivative (with respect to `x`) for mode parameters m>=0
10937 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
10938 pre-computed characteristic value.
10940 Parameters
10941 ----------
10942 m : array_like
10943 Mode parameter m (nonnegative)
10944 n : array_like
10945 Mode parameter n (>= m)
10946 c : array_like
10947 Spheroidal parameter
10948 cv : array_like
10949 Characteristic value
10950 x : array_like
10951 Parameter x (``|x| < 1.0``)
10952 out : ndarray, optional
10953 Optional output array for the function results
10955 Returns
10956 -------
10957 s : scalar or ndarray
10958 Value of the function
10959 sp : scalar or ndarray
10960 Value of the derivative vs x
10962 See Also
10963 --------
10964 obl_rad2
10965 """)
10967add_newdoc("pbdv",
10968 """
10969 pbdv(v, x, out=None)
10971 Parabolic cylinder function D
10973 Returns (d, dp) the parabolic cylinder function Dv(x) in d and the
10974 derivative, Dv'(x) in dp.
10976 Parameters
10977 ----------
10978 v : array_like
10979 Real parameter
10980 x : array_like
10981 Real argument
10982 out : ndarray, optional
10983 Optional output array for the function results
10985 Returns
10986 -------
10987 d : scalar or ndarray
10988 Value of the function
10989 dp : scalar or ndarray
10990 Value of the derivative vs x
10991 """)
10993add_newdoc("pbvv",
10994 """
10995 pbvv(v, x, out=None)
10997 Parabolic cylinder function V
10999 Returns the parabolic cylinder function Vv(x) in v and the
11000 derivative, Vv'(x) in vp.
11002 Parameters
11003 ----------
11004 v : array_like
11005 Real parameter
11006 x : array_like
11007 Real argument
11008 out : ndarray, optional
11009 Optional output array for the function results
11011 Returns
11012 -------
11013 v : scalar or ndarray
11014 Value of the function
11015 vp : scalar or ndarray
11016 Value of the derivative vs x
11017 """)
11019add_newdoc("pbwa",
11020 r"""
11021 pbwa(a, x, out=None)
11023 Parabolic cylinder function W.
11025 The function is a particular solution to the differential equation
11027 .. math::
11029 y'' + \left(\frac{1}{4}x^2 - a\right)y = 0,
11031 for a full definition see section 12.14 in [1]_.
11033 Parameters
11034 ----------
11035 a : array_like
11036 Real parameter
11037 x : array_like
11038 Real argument
11039 out : ndarray, optional
11040 Optional output array for the function results
11042 Returns
11043 -------
11044 w : scalar or ndarray
11045 Value of the function
11046 wp : scalar or ndarray
11047 Value of the derivative in x
11049 Notes
11050 -----
11051 The function is a wrapper for a Fortran routine by Zhang and Jin
11052 [2]_. The implementation is accurate only for ``|a|, |x| < 5`` and
11053 returns NaN outside that range.
11055 References
11056 ----------
11057 .. [1] Digital Library of Mathematical Functions, 14.30.
11058 https://dlmf.nist.gov/14.30
11059 .. [2] Zhang, Shanjie and Jin, Jianming. "Computation of Special
11060 Functions", John Wiley and Sons, 1996.
11061 https://people.sc.fsu.edu/~jburkardt/f_src/special_functions/special_functions.html
11062 """)
11064add_newdoc("pdtr",
11065 r"""
11066 pdtr(k, m, out=None)
11068 Poisson cumulative distribution function.
11070 Defined as the probability that a Poisson-distributed random
11071 variable with event rate :math:`m` is less than or equal to
11072 :math:`k`. More concretely, this works out to be [1]_
11074 .. math::
11076 \exp(-m) \sum_{j = 0}^{\lfloor{k}\rfloor} \frac{m^j}{j!}.
11078 Parameters
11079 ----------
11080 k : array_like
11081 Number of occurrences (nonnegative, real)
11082 m : array_like
11083 Shape parameter (nonnegative, real)
11084 out : ndarray, optional
11085 Optional output array for the function results
11087 Returns
11088 -------
11089 scalar or ndarray
11090 Values of the Poisson cumulative distribution function
11092 See Also
11093 --------
11094 pdtrc : Poisson survival function
11095 pdtrik : inverse of `pdtr` with respect to `k`
11096 pdtri : inverse of `pdtr` with respect to `m`
11098 References
11099 ----------
11100 .. [1] https://en.wikipedia.org/wiki/Poisson_distribution
11102 Examples
11103 --------
11104 >>> import numpy as np
11105 >>> import scipy.special as sc
11107 It is a cumulative distribution function, so it converges to 1
11108 monotonically as `k` goes to infinity.
11110 >>> sc.pdtr([1, 10, 100, np.inf], 1)
11111 array([0.73575888, 0.99999999, 1. , 1. ])
11113 It is discontinuous at integers and constant between integers.
11115 >>> sc.pdtr([1, 1.5, 1.9, 2], 1)
11116 array([0.73575888, 0.73575888, 0.73575888, 0.9196986 ])
11118 """)
11120add_newdoc("pdtrc",
11121 """
11122 pdtrc(k, m, out=None)
11124 Poisson survival function
11126 Returns the sum of the terms from k+1 to infinity of the Poisson
11127 distribution: sum(exp(-m) * m**j / j!, j=k+1..inf) = gammainc(
11128 k+1, m). Arguments must both be non-negative doubles.
11130 Parameters
11131 ----------
11132 k : array_like
11133 Number of occurrences (nonnegative, real)
11134 m : array_like
11135 Shape parameter (nonnegative, real)
11136 out : ndarray, optional
11137 Optional output array for the function results
11139 Returns
11140 -------
11141 scalar or ndarray
11142 Values of the Poisson survival function
11144 See Also
11145 --------
11146 pdtr : Poisson cumulative distribution function
11147 pdtrik : inverse of `pdtr` with respect to `k`
11148 pdtri : inverse of `pdtr` with respect to `m`
11150 """)
11152add_newdoc("pdtri",
11153 """
11154 pdtri(k, y, out=None)
11156 Inverse to `pdtr` vs m
11158 Returns the Poisson variable `m` such that the sum from 0 to `k` of
11159 the Poisson density is equal to the given probability `y`:
11160 calculated by ``gammaincinv(k + 1, y)``. `k` must be a nonnegative
11161 integer and `y` between 0 and 1.
11163 Parameters
11164 ----------
11165 k : array_like
11166 Number of occurrences (nonnegative, real)
11167 y : array_like
11168 Probability
11169 out : ndarray, optional
11170 Optional output array for the function results
11172 Returns
11173 -------
11174 scalar or ndarray
11175 Values of the shape paramter `m` such that ``pdtr(k, m) = p``
11177 See Also
11178 --------
11179 pdtr : Poisson cumulative distribution function
11180 pdtrc : Poisson survival function
11181 pdtrik : inverse of `pdtr` with respect to `k`
11183 """)
11185add_newdoc("pdtrik",
11186 """
11187 pdtrik(p, m, out=None)
11189 Inverse to `pdtr` vs `m`.
11191 Parameters
11192 ----------
11193 m : array_like
11194 Shape parameter (nonnegative, real)
11195 p : array_like
11196 Probability
11197 out : ndarray, optional
11198 Optional output array for the function results
11200 Returns
11201 -------
11202 scalar or ndarray
11203 The number of occurrences `k` such that ``pdtr(k, m) = p``
11205 See Also
11206 --------
11207 pdtr : Poisson cumulative distribution function
11208 pdtrc : Poisson survival function
11209 pdtri : inverse of `pdtr` with respect to `m`
11211 """)
11213add_newdoc("poch",
11214 r"""
11215 poch(z, m, out=None)
11217 Pochhammer symbol.
11219 The Pochhammer symbol (rising factorial) is defined as
11221 .. math::
11223 (z)_m = \frac{\Gamma(z + m)}{\Gamma(z)}
11225 For positive integer `m` it reads
11227 .. math::
11229 (z)_m = z (z + 1) ... (z + m - 1)
11231 See [dlmf]_ for more details.
11233 Parameters
11234 ----------
11235 z, m : array_like
11236 Real-valued arguments.
11237 out : ndarray, optional
11238 Optional output array for the function results
11240 Returns
11241 -------
11242 scalar or ndarray
11243 The value of the function.
11245 References
11246 ----------
11247 .. [dlmf] Nist, Digital Library of Mathematical Functions
11248 https://dlmf.nist.gov/5.2#iii
11250 Examples
11251 --------
11252 >>> import scipy.special as sc
11254 It is 1 when m is 0.
11256 >>> sc.poch([1, 2, 3, 4], 0)
11257 array([1., 1., 1., 1.])
11259 For z equal to 1 it reduces to the factorial function.
11261 >>> sc.poch(1, 5)
11262 120.0
11263 >>> 1 * 2 * 3 * 4 * 5
11264 120
11266 It can be expressed in terms of the gamma function.
11268 >>> z, m = 3.7, 2.1
11269 >>> sc.poch(z, m)
11270 20.529581933776953
11271 >>> sc.gamma(z + m) / sc.gamma(z)
11272 20.52958193377696
11274 """)
11276add_newdoc("powm1", """
11277 powm1(x, y, out=None)
11279 Computes ``x**y - 1``.
11281 This function is useful when `y` is near 0, or when `x` is near 1.
11283 The function is implemented for real types only (unlike ``numpy.power``,
11284 which accepts complex inputs).
11286 Parameters
11287 ----------
11288 x : array_like
11289 The base. Must be a real type (i.e. integer or float, not complex).
11290 y : array_like
11291 The exponent. Must be a real type (i.e. integer or float, not complex).
11293 Returns
11294 -------
11295 array_like
11296 Result of the calculation
11298 Notes
11299 -----
11300 .. versionadded:: 1.10.0
11302 The underlying code is implemented for single precision and double
11303 precision floats only. Unlike `numpy.power`, integer inputs to
11304 `powm1` are converted to floating point, and complex inputs are
11305 not accepted.
11307 Note the following edge cases:
11309 * ``powm1(x, 0)`` returns 0 for any ``x``, including 0, ``inf``
11310 and ``nan``.
11311 * ``powm1(1, y)`` returns 0 for any ``y``, including ``nan``
11312 and ``inf``.
11314 Examples
11315 --------
11316 >>> import numpy as np
11317 >>> from scipy.special import powm1
11319 >>> x = np.array([1.2, 10.0, 0.9999999975])
11320 >>> y = np.array([1e-9, 1e-11, 0.1875])
11321 >>> powm1(x, y)
11322 array([ 1.82321557e-10, 2.30258509e-11, -4.68749998e-10])
11324 It can be verified that the relative errors in those results
11325 are less than 2.5e-16.
11327 Compare that to the result of ``x**y - 1``, where the
11328 relative errors are all larger than 8e-8:
11330 >>> x**y - 1
11331 array([ 1.82321491e-10, 2.30258035e-11, -4.68750039e-10])
11333 """)
11336add_newdoc("pro_ang1",
11337 """
11338 pro_ang1(m, n, c, x, out=None)
11340 Prolate spheroidal angular function of the first kind and its derivative
11342 Computes the prolate spheroidal angular function of the first kind
11343 and its derivative (with respect to `x`) for mode parameters m>=0
11344 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11346 Parameters
11347 ----------
11348 m : array_like
11349 Nonnegative mode parameter m
11350 n : array_like
11351 Mode parameter n (>= m)
11352 c : array_like
11353 Spheroidal parameter
11354 x : array_like
11355 Real parameter (``|x| < 1.0``)
11356 out : ndarray, optional
11357 Optional output array for the function results
11359 Returns
11360 -------
11361 s : scalar or ndarray
11362 Value of the function
11363 sp : scalar or ndarray
11364 Value of the derivative vs x
11365 """)
11367add_newdoc("pro_ang1_cv",
11368 """
11369 pro_ang1_cv(m, n, c, cv, x, out=None)
11371 Prolate spheroidal angular function pro_ang1 for precomputed characteristic value
11373 Computes the prolate spheroidal angular function of the first kind
11374 and its derivative (with respect to `x`) for mode parameters m>=0
11375 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11376 pre-computed characteristic value.
11378 Parameters
11379 ----------
11380 m : array_like
11381 Nonnegative mode parameter m
11382 n : array_like
11383 Mode parameter n (>= m)
11384 c : array_like
11385 Spheroidal parameter
11386 cv : array_like
11387 Characteristic value
11388 x : array_like
11389 Real parameter (``|x| < 1.0``)
11390 out : ndarray, optional
11391 Optional output array for the function results
11393 Returns
11394 -------
11395 s : scalar or ndarray
11396 Value of the function
11397 sp : scalar or ndarray
11398 Value of the derivative vs x
11399 """)
11401add_newdoc("pro_cv",
11402 """
11403 pro_cv(m, n, c, out=None)
11405 Characteristic value of prolate spheroidal function
11407 Computes the characteristic value of prolate spheroidal wave
11408 functions of order `m`, `n` (n>=m) and spheroidal parameter `c`.
11410 Parameters
11411 ----------
11412 m : array_like
11413 Nonnegative mode parameter m
11414 n : array_like
11415 Mode parameter n (>= m)
11416 c : array_like
11417 Spheroidal parameter
11418 out : ndarray, optional
11419 Optional output array for the function results
11421 Returns
11422 -------
11423 cv : scalar or ndarray
11424 Characteristic value
11425 """)
11427add_newdoc("pro_rad1",
11428 """
11429 pro_rad1(m, n, c, x, out=None)
11431 Prolate spheroidal radial function of the first kind and its derivative
11433 Computes the prolate spheroidal radial function of the first kind
11434 and its derivative (with respect to `x`) for mode parameters m>=0
11435 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11437 Parameters
11438 ----------
11439 m : array_like
11440 Nonnegative mode parameter m
11441 n : array_like
11442 Mode parameter n (>= m)
11443 c : array_like
11444 Spheroidal parameter
11445 x : array_like
11446 Real parameter (``|x| < 1.0``)
11447 out : ndarray, optional
11448 Optional output array for the function results
11450 Returns
11451 -------
11452 s : scalar or ndarray
11453 Value of the function
11454 sp : scalar or ndarray
11455 Value of the derivative vs x
11456 """)
11458add_newdoc("pro_rad1_cv",
11459 """
11460 pro_rad1_cv(m, n, c, cv, x, out=None)
11462 Prolate spheroidal radial function pro_rad1 for precomputed characteristic value
11464 Computes the prolate spheroidal radial function of the first kind
11465 and its derivative (with respect to `x`) for mode parameters m>=0
11466 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11467 pre-computed characteristic value.
11469 Parameters
11470 ----------
11471 m : array_like
11472 Nonnegative mode parameter m
11473 n : array_like
11474 Mode parameter n (>= m)
11475 c : array_like
11476 Spheroidal parameter
11477 cv : array_like
11478 Characteristic value
11479 x : array_like
11480 Real parameter (``|x| < 1.0``)
11481 out : ndarray, optional
11482 Optional output array for the function results
11484 Returns
11485 -------
11486 s : scalar or ndarray
11487 Value of the function
11488 sp : scalar or ndarray
11489 Value of the derivative vs x
11490 """)
11492add_newdoc("pro_rad2",
11493 """
11494 pro_rad2(m, n, c, x, out=None)
11496 Prolate spheroidal radial function of the second kind and its derivative
11498 Computes the prolate spheroidal radial function of the second kind
11499 and its derivative (with respect to `x`) for mode parameters m>=0
11500 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``.
11502 Parameters
11503 ----------
11504 m : array_like
11505 Nonnegative mode parameter m
11506 n : array_like
11507 Mode parameter n (>= m)
11508 c : array_like
11509 Spheroidal parameter
11510 cv : array_like
11511 Characteristic value
11512 x : array_like
11513 Real parameter (``|x| < 1.0``)
11514 out : ndarray, optional
11515 Optional output array for the function results
11517 Returns
11518 -------
11519 s : scalar or ndarray
11520 Value of the function
11521 sp : scalar or ndarray
11522 Value of the derivative vs x
11523 """)
11525add_newdoc("pro_rad2_cv",
11526 """
11527 pro_rad2_cv(m, n, c, cv, x, out=None)
11529 Prolate spheroidal radial function pro_rad2 for precomputed characteristic value
11531 Computes the prolate spheroidal radial function of the second kind
11532 and its derivative (with respect to `x`) for mode parameters m>=0
11533 and n>=m, spheroidal parameter `c` and ``|x| < 1.0``. Requires
11534 pre-computed characteristic value.
11536 Parameters
11537 ----------
11538 m : array_like
11539 Nonnegative mode parameter m
11540 n : array_like
11541 Mode parameter n (>= m)
11542 c : array_like
11543 Spheroidal parameter
11544 cv : array_like
11545 Characteristic value
11546 x : array_like
11547 Real parameter (``|x| < 1.0``)
11548 out : ndarray, optional
11549 Optional output array for the function results
11551 Returns
11552 -------
11553 s : scalar or ndarray
11554 Value of the function
11555 sp : scalar or ndarray
11556 Value of the derivative vs x
11557 """)
11559add_newdoc("pseudo_huber",
11560 r"""
11561 pseudo_huber(delta, r, out=None)
11563 Pseudo-Huber loss function.
11565 .. math:: \mathrm{pseudo\_huber}(\delta, r) = \delta^2 \left( \sqrt{ 1 + \left( \frac{r}{\delta} \right)^2 } - 1 \right)
11567 Parameters
11568 ----------
11569 delta : array_like
11570 Input array, indicating the soft quadratic vs. linear loss changepoint.
11571 r : array_like
11572 Input array, possibly representing residuals.
11573 out : ndarray, optional
11574 Optional output array for the function results
11576 Returns
11577 -------
11578 res : scalar or ndarray
11579 The computed Pseudo-Huber loss function values.
11581 See also
11582 --------
11583 huber: Similar function which this function approximates
11585 Notes
11586 -----
11587 Like `huber`, `pseudo_huber` often serves as a robust loss function
11588 in statistics or machine learning to reduce the influence of outliers.
11589 Unlike `huber`, `pseudo_huber` is smooth.
11591 Typically, `r` represents residuals, the difference
11592 between a model prediction and data. Then, for :math:`|r|\leq\delta`,
11593 `pseudo_huber` resembles the squared error and for :math:`|r|>\delta` the
11594 absolute error. This way, the Pseudo-Huber loss often achieves
11595 a fast convergence in model fitting for small residuals like the squared
11596 error loss function and still reduces the influence of outliers
11597 (:math:`|r|>\delta`) like the absolute error loss. As :math:`\delta` is
11598 the cutoff between squared and absolute error regimes, it has
11599 to be tuned carefully for each problem. `pseudo_huber` is also
11600 convex, making it suitable for gradient based optimization. [1]_ [2]_
11602 .. versionadded:: 0.15.0
11604 References
11605 ----------
11606 .. [1] Hartley, Zisserman, "Multiple View Geometry in Computer Vision".
11607 2003. Cambridge University Press. p. 619
11608 .. [2] Charbonnier et al. "Deterministic edge-preserving regularization
11609 in computed imaging". 1997. IEEE Trans. Image Processing.
11610 6 (2): 298 - 311.
11612 Examples
11613 --------
11614 Import all necessary modules.
11616 >>> import numpy as np
11617 >>> from scipy.special import pseudo_huber, huber
11618 >>> import matplotlib.pyplot as plt
11620 Calculate the function for ``delta=1`` at ``r=2``.
11622 >>> pseudo_huber(1., 2.)
11623 1.2360679774997898
11625 Calculate the function at ``r=2`` for different `delta` by providing
11626 a list or NumPy array for `delta`.
11628 >>> pseudo_huber([1., 2., 4.], 3.)
11629 array([2.16227766, 3.21110255, 4. ])
11631 Calculate the function for ``delta=1`` at several points by providing
11632 a list or NumPy array for `r`.
11634 >>> pseudo_huber(2., np.array([1., 1.5, 3., 4.]))
11635 array([0.47213595, 1. , 3.21110255, 4.94427191])
11637 The function can be calculated for different `delta` and `r` by
11638 providing arrays for both with compatible shapes for broadcasting.
11640 >>> r = np.array([1., 2.5, 8., 10.])
11641 >>> deltas = np.array([[1.], [5.], [9.]])
11642 >>> print(r.shape, deltas.shape)
11643 (4,) (3, 1)
11645 >>> pseudo_huber(deltas, r)
11646 array([[ 0.41421356, 1.6925824 , 7.06225775, 9.04987562],
11647 [ 0.49509757, 2.95084972, 22.16990566, 30.90169944],
11648 [ 0.49846624, 3.06693762, 27.37435121, 40.08261642]])
11650 Plot the function for different `delta`.
11652 >>> x = np.linspace(-4, 4, 500)
11653 >>> deltas = [1, 2, 3]
11654 >>> linestyles = ["dashed", "dotted", "dashdot"]
11655 >>> fig, ax = plt.subplots()
11656 >>> combined_plot_parameters = list(zip(deltas, linestyles))
11657 >>> for delta, style in combined_plot_parameters:
11658 ... ax.plot(x, pseudo_huber(delta, x), label=f"$\delta={delta}$",
11659 ... ls=style)
11660 >>> ax.legend(loc="upper center")
11661 >>> ax.set_xlabel("$x$")
11662 >>> ax.set_title("Pseudo-Huber loss function $h_{\delta}(x)$")
11663 >>> ax.set_xlim(-4, 4)
11664 >>> ax.set_ylim(0, 8)
11665 >>> plt.show()
11667 Finally, illustrate the difference between `huber` and `pseudo_huber` by
11668 plotting them and their gradients with respect to `r`. The plot shows
11669 that `pseudo_huber` is continuously differentiable while `huber` is not
11670 at the points :math:`\pm\delta`.
11672 >>> def huber_grad(delta, x):
11673 ... grad = np.copy(x)
11674 ... linear_area = np.argwhere(np.abs(x) > delta)
11675 ... grad[linear_area]=delta*np.sign(x[linear_area])
11676 ... return grad
11677 >>> def pseudo_huber_grad(delta, x):
11678 ... return x* (1+(x/delta)**2)**(-0.5)
11679 >>> x=np.linspace(-3, 3, 500)
11680 >>> delta = 1.
11681 >>> fig, ax = plt.subplots(figsize=(7, 7))
11682 >>> ax.plot(x, huber(delta, x), label="Huber", ls="dashed")
11683 >>> ax.plot(x, huber_grad(delta, x), label="Huber Gradient", ls="dashdot")
11684 >>> ax.plot(x, pseudo_huber(delta, x), label="Pseudo-Huber", ls="dotted")
11685 >>> ax.plot(x, pseudo_huber_grad(delta, x), label="Pseudo-Huber Gradient",
11686 ... ls="solid")
11687 >>> ax.legend(loc="upper center")
11688 >>> plt.show()
11689 """)
11691add_newdoc("psi",
11692 """
11693 psi(z, out=None)
11695 The digamma function.
11697 The logarithmic derivative of the gamma function evaluated at ``z``.
11699 Parameters
11700 ----------
11701 z : array_like
11702 Real or complex argument.
11703 out : ndarray, optional
11704 Array for the computed values of ``psi``.
11706 Returns
11707 -------
11708 digamma : scalar or ndarray
11709 Computed values of ``psi``.
11711 Notes
11712 -----
11713 For large values not close to the negative real axis, ``psi`` is
11714 computed using the asymptotic series (5.11.2) from [1]_. For small
11715 arguments not close to the negative real axis, the recurrence
11716 relation (5.5.2) from [1]_ is used until the argument is large
11717 enough to use the asymptotic series. For values close to the
11718 negative real axis, the reflection formula (5.5.4) from [1]_ is
11719 used first. Note that ``psi`` has a family of zeros on the
11720 negative real axis which occur between the poles at nonpositive
11721 integers. Around the zeros the reflection formula suffers from
11722 cancellation and the implementation loses precision. The sole
11723 positive zero and the first negative zero, however, are handled
11724 separately by precomputing series expansions using [2]_, so the
11725 function should maintain full accuracy around the origin.
11727 References
11728 ----------
11729 .. [1] NIST Digital Library of Mathematical Functions
11730 https://dlmf.nist.gov/5
11731 .. [2] Fredrik Johansson and others.
11732 "mpmath: a Python library for arbitrary-precision floating-point arithmetic"
11733 (Version 0.19) http://mpmath.org/
11735 Examples
11736 --------
11737 >>> from scipy.special import psi
11738 >>> z = 3 + 4j
11739 >>> psi(z)
11740 (1.55035981733341+1.0105022091860445j)
11742 Verify psi(z) = psi(z + 1) - 1/z:
11744 >>> psi(z + 1) - 1/z
11745 (1.55035981733341+1.0105022091860445j)
11746 """)
11748add_newdoc("radian",
11749 """
11750 radian(d, m, s, out=None)
11752 Convert from degrees to radians.
11754 Returns the angle given in (d)egrees, (m)inutes, and (s)econds in
11755 radians.
11757 Parameters
11758 ----------
11759 d : array_like
11760 Degrees, can be real-valued.
11761 m : array_like
11762 Minutes, can be real-valued.
11763 s : array_like
11764 Seconds, can be real-valued.
11765 out : ndarray, optional
11766 Optional output array for the function results.
11768 Returns
11769 -------
11770 scalar or ndarray
11771 Values of the inputs in radians.
11773 Examples
11774 --------
11775 >>> import scipy.special as sc
11777 There are many ways to specify an angle.
11779 >>> sc.radian(90, 0, 0)
11780 1.5707963267948966
11781 >>> sc.radian(0, 60 * 90, 0)
11782 1.5707963267948966
11783 >>> sc.radian(0, 0, 60**2 * 90)
11784 1.5707963267948966
11786 The inputs can be real-valued.
11788 >>> sc.radian(1.5, 0, 0)
11789 0.02617993877991494
11790 >>> sc.radian(1, 30, 0)
11791 0.02617993877991494
11793 """)
11795add_newdoc("rel_entr",
11796 r"""
11797 rel_entr(x, y, out=None)
11799 Elementwise function for computing relative entropy.
11801 .. math::
11803 \mathrm{rel\_entr}(x, y) =
11804 \begin{cases}
11805 x \log(x / y) & x > 0, y > 0 \\
11806 0 & x = 0, y \ge 0 \\
11807 \infty & \text{otherwise}
11808 \end{cases}
11810 Parameters
11811 ----------
11812 x, y : array_like
11813 Input arrays
11814 out : ndarray, optional
11815 Optional output array for the function results
11817 Returns
11818 -------
11819 scalar or ndarray
11820 Relative entropy of the inputs
11822 See Also
11823 --------
11824 entr, kl_div, scipy.stats.entropy
11826 Notes
11827 -----
11828 .. versionadded:: 0.15.0
11830 This function is jointly convex in x and y.
11832 The origin of this function is in convex programming; see
11833 [1]_. Given two discrete probability distributions :math:`p_1,
11834 \ldots, p_n` and :math:`q_1, \ldots, q_n`, the definition of relative
11835 entropy in the context of *information theory* is
11837 .. math::
11839 \sum_{i = 1}^n \mathrm{rel\_entr}(p_i, q_i).
11841 To compute the latter quantity, use `scipy.stats.entropy`.
11843 See [2]_ for details.
11845 References
11846 ----------
11847 .. [1] Boyd, Stephen and Lieven Vandenberghe. *Convex optimization*.
11848 Cambridge University Press, 2004.
11849 :doi:`https://doi.org/10.1017/CBO9780511804441`
11850 .. [2] Kullback-Leibler divergence,
11851 https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence
11853 """)
11855add_newdoc("rgamma",
11856 r"""
11857 rgamma(z, out=None)
11859 Reciprocal of the gamma function.
11861 Defined as :math:`1 / \Gamma(z)`, where :math:`\Gamma` is the
11862 gamma function. For more on the gamma function see `gamma`.
11864 Parameters
11865 ----------
11866 z : array_like
11867 Real or complex valued input
11868 out : ndarray, optional
11869 Optional output array for the function results
11871 Returns
11872 -------
11873 scalar or ndarray
11874 Function results
11876 Notes
11877 -----
11878 The gamma function has no zeros and has simple poles at
11879 nonpositive integers, so `rgamma` is an entire function with zeros
11880 at the nonpositive integers. See the discussion in [dlmf]_ for
11881 more details.
11883 See Also
11884 --------
11885 gamma, gammaln, loggamma
11887 References
11888 ----------
11889 .. [dlmf] Nist, Digital Library of Mathematical functions,
11890 https://dlmf.nist.gov/5.2#i
11892 Examples
11893 --------
11894 >>> import scipy.special as sc
11896 It is the reciprocal of the gamma function.
11898 >>> sc.rgamma([1, 2, 3, 4])
11899 array([1. , 1. , 0.5 , 0.16666667])
11900 >>> 1 / sc.gamma([1, 2, 3, 4])
11901 array([1. , 1. , 0.5 , 0.16666667])
11903 It is zero at nonpositive integers.
11905 >>> sc.rgamma([0, -1, -2, -3])
11906 array([0., 0., 0., 0.])
11908 It rapidly underflows to zero along the positive real axis.
11910 >>> sc.rgamma([10, 100, 179])
11911 array([2.75573192e-006, 1.07151029e-156, 0.00000000e+000])
11913 """)
11915add_newdoc("round",
11916 """
11917 round(x, out=None)
11919 Round to the nearest integer.
11921 Returns the nearest integer to `x`. If `x` ends in 0.5 exactly,
11922 the nearest even integer is chosen.
11924 Parameters
11925 ----------
11926 x : array_like
11927 Real valued input.
11928 out : ndarray, optional
11929 Optional output array for the function results.
11931 Returns
11932 -------
11933 scalar or ndarray
11934 The nearest integers to the elements of `x`. The result is of
11935 floating type, not integer type.
11937 Examples
11938 --------
11939 >>> import scipy.special as sc
11941 It rounds to even.
11943 >>> sc.round([0.5, 1.5])
11944 array([0., 2.])
11946 """)
11948add_newdoc("shichi",
11949 r"""
11950 shichi(x, out=None)
11952 Hyperbolic sine and cosine integrals.
11954 The hyperbolic sine integral is
11956 .. math::
11958 \int_0^x \frac{\sinh{t}}{t}dt
11960 and the hyperbolic cosine integral is
11962 .. math::
11964 \gamma + \log(x) + \int_0^x \frac{\cosh{t} - 1}{t} dt
11966 where :math:`\gamma` is Euler's constant and :math:`\log` is the
11967 principal branch of the logarithm [1]_.
11969 Parameters
11970 ----------
11971 x : array_like
11972 Real or complex points at which to compute the hyperbolic sine
11973 and cosine integrals.
11974 out : tuple of ndarray, optional
11975 Optional output arrays for the function results
11977 Returns
11978 -------
11979 si : scalar or ndarray
11980 Hyperbolic sine integral at ``x``
11981 ci : scalar or ndarray
11982 Hyperbolic cosine integral at ``x``
11984 See Also
11985 --------
11986 sici : Sine and cosine integrals.
11987 exp1 : Exponential integral E1.
11988 expi : Exponential integral Ei.
11990 Notes
11991 -----
11992 For real arguments with ``x < 0``, ``chi`` is the real part of the
11993 hyperbolic cosine integral. For such points ``chi(x)`` and ``chi(x
11994 + 0j)`` differ by a factor of ``1j*pi``.
11996 For real arguments the function is computed by calling Cephes'
11997 [2]_ *shichi* routine. For complex arguments the algorithm is based
11998 on Mpmath's [3]_ *shi* and *chi* routines.
12000 References
12001 ----------
12002 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
12003 Handbook of Mathematical Functions with Formulas,
12004 Graphs, and Mathematical Tables. New York: Dover, 1972.
12005 (See Section 5.2.)
12006 .. [2] Cephes Mathematical Functions Library,
12007 http://www.netlib.org/cephes/
12008 .. [3] Fredrik Johansson and others.
12009 "mpmath: a Python library for arbitrary-precision floating-point
12010 arithmetic" (Version 0.19) http://mpmath.org/
12012 Examples
12013 --------
12014 >>> import numpy as np
12015 >>> import matplotlib.pyplot as plt
12016 >>> from scipy.special import shichi, sici
12018 `shichi` accepts real or complex input:
12020 >>> shichi(0.5)
12021 (0.5069967498196671, -0.05277684495649357)
12022 >>> shichi(0.5 + 2.5j)
12023 ((0.11772029666668238+1.831091777729851j),
12024 (0.29912435887648825+1.7395351121166562j))
12026 The hyperbolic sine and cosine integrals Shi(z) and Chi(z) are
12027 related to the sine and cosine integrals Si(z) and Ci(z) by
12029 * Shi(z) = -i*Si(i*z)
12030 * Chi(z) = Ci(-i*z) + i*pi/2
12032 >>> z = 0.25 + 5j
12033 >>> shi, chi = shichi(z)
12034 >>> shi, -1j*sici(1j*z)[0] # Should be the same.
12035 ((-0.04834719325101729+1.5469354086921228j),
12036 (-0.04834719325101729+1.5469354086921228j))
12037 >>> chi, sici(-1j*z)[1] + 1j*np.pi/2 # Should be the same.
12038 ((-0.19568708973868087+1.556276312103824j),
12039 (-0.19568708973868087+1.556276312103824j))
12041 Plot the functions evaluated on the real axis:
12043 >>> xp = np.geomspace(1e-8, 4.0, 250)
12044 >>> x = np.concatenate((-xp[::-1], xp))
12045 >>> shi, chi = shichi(x)
12047 >>> fig, ax = plt.subplots()
12048 >>> ax.plot(x, shi, label='Shi(x)')
12049 >>> ax.plot(x, chi, '--', label='Chi(x)')
12050 >>> ax.set_xlabel('x')
12051 >>> ax.set_title('Hyperbolic Sine and Cosine Integrals')
12052 >>> ax.legend(shadow=True, framealpha=1, loc='lower right')
12053 >>> ax.grid(True)
12054 >>> plt.show()
12056 """)
12058add_newdoc("sici",
12059 r"""
12060 sici(x, out=None)
12062 Sine and cosine integrals.
12064 The sine integral is
12066 .. math::
12068 \int_0^x \frac{\sin{t}}{t}dt
12070 and the cosine integral is
12072 .. math::
12074 \gamma + \log(x) + \int_0^x \frac{\cos{t} - 1}{t}dt
12076 where :math:`\gamma` is Euler's constant and :math:`\log` is the
12077 principal branch of the logarithm [1]_.
12079 Parameters
12080 ----------
12081 x : array_like
12082 Real or complex points at which to compute the sine and cosine
12083 integrals.
12084 out : tuple of ndarray, optional
12085 Optional output arrays for the function results
12087 Returns
12088 -------
12089 si : scalar or ndarray
12090 Sine integral at ``x``
12091 ci : scalar or ndarray
12092 Cosine integral at ``x``
12094 See Also
12095 --------
12096 shichi : Hyperbolic sine and cosine integrals.
12097 exp1 : Exponential integral E1.
12098 expi : Exponential integral Ei.
12100 Notes
12101 -----
12102 For real arguments with ``x < 0``, ``ci`` is the real part of the
12103 cosine integral. For such points ``ci(x)`` and ``ci(x + 0j)``
12104 differ by a factor of ``1j*pi``.
12106 For real arguments the function is computed by calling Cephes'
12107 [2]_ *sici* routine. For complex arguments the algorithm is based
12108 on Mpmath's [3]_ *si* and *ci* routines.
12110 References
12111 ----------
12112 .. [1] Milton Abramowitz and Irene A. Stegun, eds.
12113 Handbook of Mathematical Functions with Formulas,
12114 Graphs, and Mathematical Tables. New York: Dover, 1972.
12115 (See Section 5.2.)
12116 .. [2] Cephes Mathematical Functions Library,
12117 http://www.netlib.org/cephes/
12118 .. [3] Fredrik Johansson and others.
12119 "mpmath: a Python library for arbitrary-precision floating-point
12120 arithmetic" (Version 0.19) http://mpmath.org/
12122 Examples
12123 --------
12124 >>> import numpy as np
12125 >>> import matplotlib.pyplot as plt
12126 >>> from scipy.special import sici, exp1
12128 `sici` accepts real or complex input:
12130 >>> sici(2.5)
12131 (1.7785201734438267, 0.2858711963653835)
12132 >>> sici(2.5 + 3j)
12133 ((4.505735874563953+0.06863305018999577j),
12134 (0.0793644206906966-2.935510262937543j))
12136 For z in the right half plane, the sine and cosine integrals are
12137 related to the exponential integral E1 (implemented in SciPy as
12138 `scipy.special.exp1`) by
12140 * Si(z) = (E1(i*z) - E1(-i*z))/2i + pi/2
12141 * Ci(z) = -(E1(i*z) + E1(-i*z))/2
12143 See [1]_ (equations 5.2.21 and 5.2.23).
12145 We can verify these relations:
12147 >>> z = 2 - 3j
12148 >>> sici(z)
12149 ((4.54751388956229-1.3991965806460565j),
12150 (1.408292501520851+2.9836177420296055j))
12152 >>> (exp1(1j*z) - exp1(-1j*z))/2j + np.pi/2 # Same as sine integral
12153 (4.54751388956229-1.3991965806460565j)
12155 >>> -(exp1(1j*z) + exp1(-1j*z))/2 # Same as cosine integral
12156 (1.408292501520851+2.9836177420296055j)
12158 Plot the functions evaluated on the real axis; the dotted horizontal
12159 lines are at pi/2 and -pi/2:
12161 >>> x = np.linspace(-16, 16, 150)
12162 >>> si, ci = sici(x)
12164 >>> fig, ax = plt.subplots()
12165 >>> ax.plot(x, si, label='Si(x)')
12166 >>> ax.plot(x, ci, '--', label='Ci(x)')
12167 >>> ax.legend(shadow=True, framealpha=1, loc='upper left')
12168 >>> ax.set_xlabel('x')
12169 >>> ax.set_title('Sine and Cosine Integrals')
12170 >>> ax.axhline(np.pi/2, linestyle=':', alpha=0.5, color='k')
12171 >>> ax.axhline(-np.pi/2, linestyle=':', alpha=0.5, color='k')
12172 >>> ax.grid(True)
12173 >>> plt.show()
12175 """)
12177add_newdoc("sindg",
12178 """
12179 sindg(x, out=None)
12181 Sine of the angle `x` given in degrees.
12183 Parameters
12184 ----------
12185 x : array_like
12186 Angle, given in degrees.
12187 out : ndarray, optional
12188 Optional output array for the function results.
12190 Returns
12191 -------
12192 scalar or ndarray
12193 Sine at the input.
12195 See Also
12196 --------
12197 cosdg, tandg, cotdg
12199 Examples
12200 --------
12201 >>> import numpy as np
12202 >>> import scipy.special as sc
12204 It is more accurate than using sine directly.
12206 >>> x = 180 * np.arange(3)
12207 >>> sc.sindg(x)
12208 array([ 0., -0., 0.])
12209 >>> np.sin(x * np.pi / 180)
12210 array([ 0.0000000e+00, 1.2246468e-16, -2.4492936e-16])
12212 """)
12214add_newdoc("smirnov",
12215 r"""
12216 smirnov(n, d, out=None)
12218 Kolmogorov-Smirnov complementary cumulative distribution function
12220 Returns the exact Kolmogorov-Smirnov complementary cumulative
12221 distribution function,(aka the Survival Function) of Dn+ (or Dn-)
12222 for a one-sided test of equality between an empirical and a
12223 theoretical distribution. It is equal to the probability that the
12224 maximum difference between a theoretical distribution and an empirical
12225 one based on `n` samples is greater than d.
12227 Parameters
12228 ----------
12229 n : int
12230 Number of samples
12231 d : float array_like
12232 Deviation between the Empirical CDF (ECDF) and the target CDF.
12233 out : ndarray, optional
12234 Optional output array for the function results
12236 Returns
12237 -------
12238 scalar or ndarray
12239 The value(s) of smirnov(n, d), Prob(Dn+ >= d) (Also Prob(Dn- >= d))
12241 See Also
12242 --------
12243 smirnovi : The Inverse Survival Function for the distribution
12244 scipy.stats.ksone : Provides the functionality as a continuous distribution
12245 kolmogorov, kolmogi : Functions for the two-sided distribution
12247 Notes
12248 -----
12249 `smirnov` is used by `stats.kstest` in the application of the
12250 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
12251 function is exposed in `scpy.special`, but the recommended way to achieve
12252 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
12253 `stats.ksone` distribution.
12255 Examples
12256 --------
12257 >>> import numpy as np
12258 >>> from scipy.special import smirnov
12259 >>> from scipy.stats import norm
12261 Show the probability of a gap at least as big as 0, 0.5 and 1.0 for a
12262 sample of size 5.
12264 >>> smirnov(5, [0, 0.5, 1.0])
12265 array([ 1. , 0.056, 0. ])
12267 Compare a sample of size 5 against N(0, 1), the standard normal
12268 distribution with mean 0 and standard deviation 1.
12270 `x` is the sample.
12272 >>> x = np.array([-1.392, -0.135, 0.114, 0.190, 1.82])
12274 >>> target = norm(0, 1)
12275 >>> cdfs = target.cdf(x)
12276 >>> cdfs
12277 array([0.0819612 , 0.44630594, 0.5453811 , 0.57534543, 0.9656205 ])
12279 Construct the empirical CDF and the K-S statistics (Dn+, Dn-, Dn).
12281 >>> n = len(x)
12282 >>> ecdfs = np.arange(n+1, dtype=float)/n
12283 >>> cols = np.column_stack([x, ecdfs[1:], cdfs, cdfs - ecdfs[:n],
12284 ... ecdfs[1:] - cdfs])
12285 >>> with np.printoptions(precision=3):
12286 ... print(cols)
12287 [[-1.392 0.2 0.082 0.082 0.118]
12288 [-0.135 0.4 0.446 0.246 -0.046]
12289 [ 0.114 0.6 0.545 0.145 0.055]
12290 [ 0.19 0.8 0.575 -0.025 0.225]
12291 [ 1.82 1. 0.966 0.166 0.034]]
12292 >>> gaps = cols[:, -2:]
12293 >>> Dnpm = np.max(gaps, axis=0)
12294 >>> print(f'Dn-={Dnpm[0]:f}, Dn+={Dnpm[1]:f}')
12295 Dn-=0.246306, Dn+=0.224655
12296 >>> probs = smirnov(n, Dnpm)
12297 >>> print(f'For a sample of size {n} drawn from N(0, 1):',
12298 ... f' Smirnov n={n}: Prob(Dn- >= {Dnpm[0]:f}) = {probs[0]:.4f}',
12299 ... f' Smirnov n={n}: Prob(Dn+ >= {Dnpm[1]:f}) = {probs[1]:.4f}',
12300 ... sep='\n')
12301 For a sample of size 5 drawn from N(0, 1):
12302 Smirnov n=5: Prob(Dn- >= 0.246306) = 0.4711
12303 Smirnov n=5: Prob(Dn+ >= 0.224655) = 0.5245
12305 Plot the empirical CDF and the standard normal CDF.
12307 >>> import matplotlib.pyplot as plt
12308 >>> plt.step(np.concatenate(([-2.5], x, [2.5])),
12309 ... np.concatenate((ecdfs, [1])),
12310 ... where='post', label='Empirical CDF')
12311 >>> xx = np.linspace(-2.5, 2.5, 100)
12312 >>> plt.plot(xx, target.cdf(xx), '--', label='CDF for N(0, 1)')
12314 Add vertical lines marking Dn+ and Dn-.
12316 >>> iminus, iplus = np.argmax(gaps, axis=0)
12317 >>> plt.vlines([x[iminus]], ecdfs[iminus], cdfs[iminus], color='r',
12318 ... alpha=0.5, lw=4)
12319 >>> plt.vlines([x[iplus]], cdfs[iplus], ecdfs[iplus+1], color='m',
12320 ... alpha=0.5, lw=4)
12322 >>> plt.grid(True)
12323 >>> plt.legend(framealpha=1, shadow=True)
12324 >>> plt.show()
12325 """)
12327add_newdoc("smirnovi",
12328 """
12329 smirnovi(n, p, out=None)
12331 Inverse to `smirnov`
12333 Returns `d` such that ``smirnov(n, d) == p``, the critical value
12334 corresponding to `p`.
12336 Parameters
12337 ----------
12338 n : int
12339 Number of samples
12340 p : float array_like
12341 Probability
12342 out : ndarray, optional
12343 Optional output array for the function results
12345 Returns
12346 -------
12347 scalar or ndarray
12348 The value(s) of smirnovi(n, p), the critical values.
12350 See Also
12351 --------
12352 smirnov : The Survival Function (SF) for the distribution
12353 scipy.stats.ksone : Provides the functionality as a continuous distribution
12354 kolmogorov, kolmogi : Functions for the two-sided distribution
12355 scipy.stats.kstwobign : Two-sided Kolmogorov-Smirnov distribution, large n
12357 Notes
12358 -----
12359 `smirnov` is used by `stats.kstest` in the application of the
12360 Kolmogorov-Smirnov Goodness of Fit test. For historial reasons this
12361 function is exposed in `scpy.special`, but the recommended way to achieve
12362 the most accurate CDF/SF/PDF/PPF/ISF computations is to use the
12363 `stats.ksone` distribution.
12365 Examples
12366 --------
12367 >>> from scipy.special import smirnovi, smirnov
12369 >>> n = 24
12370 >>> deviations = [0.1, 0.2, 0.3]
12372 Use `smirnov` to compute the complementary CDF of the Smirnov
12373 distribution for the given number of samples and deviations.
12375 >>> p = smirnov(n, deviations)
12376 >>> p
12377 array([0.58105083, 0.12826832, 0.01032231])
12379 The inverse function ``smirnovi(n, p)`` returns ``deviations``.
12381 >>> smirnovi(n, p)
12382 array([0.1, 0.2, 0.3])
12384 """)
12386add_newdoc("_smirnovc",
12387 """
12388 _smirnovc(n, d)
12389 Internal function, do not use.
12390 """)
12392add_newdoc("_smirnovci",
12393 """
12394 Internal function, do not use.
12395 """)
12397add_newdoc("_smirnovp",
12398 """
12399 _smirnovp(n, p)
12400 Internal function, do not use.
12401 """)
12403add_newdoc("spence",
12404 r"""
12405 spence(z, out=None)
12407 Spence's function, also known as the dilogarithm.
12409 It is defined to be
12411 .. math::
12412 \int_1^z \frac{\log(t)}{1 - t}dt
12414 for complex :math:`z`, where the contour of integration is taken
12415 to avoid the branch cut of the logarithm. Spence's function is
12416 analytic everywhere except the negative real axis where it has a
12417 branch cut.
12419 Parameters
12420 ----------
12421 z : array_like
12422 Points at which to evaluate Spence's function
12423 out : ndarray, optional
12424 Optional output array for the function results
12426 Returns
12427 -------
12428 s : scalar or ndarray
12429 Computed values of Spence's function
12431 Notes
12432 -----
12433 There is a different convention which defines Spence's function by
12434 the integral
12436 .. math::
12437 -\int_0^z \frac{\log(1 - t)}{t}dt;
12439 this is our ``spence(1 - z)``.
12441 Examples
12442 --------
12443 >>> import numpy as np
12444 >>> from scipy.special import spence
12445 >>> import matplotlib.pyplot as plt
12447 The function is defined for complex inputs:
12449 >>> spence([1-1j, 1.5+2j, 3j, -10-5j])
12450 array([-0.20561676+0.91596559j, -0.86766909-1.39560134j,
12451 -0.59422064-2.49129918j, -1.14044398+6.80075924j])
12453 For complex inputs on the branch cut, which is the negative real axis,
12454 the function returns the limit for ``z`` with positive imaginary part.
12455 For example, in the following, note the sign change of the imaginary
12456 part of the output for ``z = -2`` and ``z = -2 - 1e-8j``:
12458 >>> spence([-2 + 1e-8j, -2, -2 - 1e-8j])
12459 array([2.32018041-3.45139229j, 2.32018042-3.4513923j ,
12460 2.32018041+3.45139229j])
12462 The function returns ``nan`` for real inputs on the branch cut:
12464 >>> spence(-1.5)
12465 nan
12467 Verify some particular values: ``spence(0) = pi**2/6``,
12468 ``spence(1) = 0`` and ``spence(2) = -pi**2/12``.
12470 >>> spence([0, 1, 2])
12471 array([ 1.64493407, 0. , -0.82246703])
12472 >>> np.pi**2/6, -np.pi**2/12
12473 (1.6449340668482264, -0.8224670334241132)
12475 Verify the identity::
12477 spence(z) + spence(1 - z) = pi**2/6 - log(z)*log(1 - z)
12479 >>> z = 3 + 4j
12480 >>> spence(z) + spence(1 - z)
12481 (-2.6523186143876067+1.8853470951513935j)
12482 >>> np.pi**2/6 - np.log(z)*np.log(1 - z)
12483 (-2.652318614387606+1.885347095151394j)
12485 Plot the function for positive real input.
12487 >>> fig, ax = plt.subplots()
12488 >>> x = np.linspace(0, 6, 400)
12489 >>> ax.plot(x, spence(x))
12490 >>> ax.grid()
12491 >>> ax.set_xlabel('x')
12492 >>> ax.set_title('spence(x)')
12493 >>> plt.show()
12494 """)
12496add_newdoc("stdtr",
12497 """
12498 stdtr(df, t, out=None)
12500 Student t distribution cumulative distribution function
12502 Returns the integral from minus infinity to t of the Student t
12503 distribution with df > 0 degrees of freedom::
12505 gamma((df+1)/2)/(sqrt(df*pi)*gamma(df/2)) *
12506 integral((1+x**2/df)**(-df/2-1/2), x=-inf..t)
12508 Parameters
12509 ----------
12510 df : array_like
12511 Degrees of freedom
12512 t : array_like
12513 Upper bound of the integral
12514 out : ndarray, optional
12515 Optional output array for the function results
12517 Returns
12518 -------
12519 scalar or ndarray
12520 Value of the Student t CDF at t
12522 See Also
12523 --------
12524 stdtridf : inverse of stdtr with respect to `df`
12525 stdtrit : inverse of stdtr with respect to `t`
12526 """)
12528add_newdoc("stdtridf",
12529 """
12530 stdtridf(p, t, out=None)
12532 Inverse of `stdtr` vs df
12534 Returns the argument df such that stdtr(df, t) is equal to `p`.
12536 Parameters
12537 ----------
12538 p : array_like
12539 Probability
12540 t : array_like
12541 Upper bound of the integral
12542 out : ndarray, optional
12543 Optional output array for the function results
12545 Returns
12546 -------
12547 df : scalar or ndarray
12548 Value of `df` such that ``stdtr(df, t) == p``
12550 See Also
12551 --------
12552 stdtr : Student t CDF
12553 stdtrit : inverse of stdtr with respect to `t`
12554 """)
12556add_newdoc("stdtrit",
12557 """
12558 stdtrit(df, p, out=None)
12560 Inverse of `stdtr` vs `t`
12562 Returns the argument `t` such that stdtr(df, t) is equal to `p`.
12564 Parameters
12565 ----------
12566 df : array_like
12567 Degrees of freedom
12568 p : array_like
12569 Probability
12570 out : ndarray, optional
12571 Optional output array for the function results
12573 Returns
12574 -------
12575 t : scalar or ndarray
12576 Value of `t` such that ``stdtr(df, t) == p``
12578 See Also
12579 --------
12580 stdtr : Student t CDF
12581 stdtridf : inverse of stdtr with respect to `df`
12583 """)
12585add_newdoc("struve",
12586 r"""
12587 struve(v, x, out=None)
12589 Struve function.
12591 Return the value of the Struve function of order `v` at `x`. The Struve
12592 function is defined as,
12594 .. math::
12595 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})},
12597 where :math:`\Gamma` is the gamma function.
12599 Parameters
12600 ----------
12601 v : array_like
12602 Order of the Struve function (float).
12603 x : array_like
12604 Argument of the Struve function (float; must be positive unless `v` is
12605 an integer).
12606 out : ndarray, optional
12607 Optional output array for the function results
12609 Returns
12610 -------
12611 H : scalar or ndarray
12612 Value of the Struve function of order `v` at `x`.
12614 Notes
12615 -----
12616 Three methods discussed in [1]_ are used to evaluate the Struve function:
12618 - power series
12619 - expansion in Bessel functions (if :math:`|z| < |v| + 20`)
12620 - asymptotic large-z expansion (if :math:`z \geq 0.7v + 12`)
12622 Rounding errors are estimated based on the largest terms in the sums, and
12623 the result associated with the smallest error is returned.
12625 See also
12626 --------
12627 modstruve: Modified Struve function
12629 References
12630 ----------
12631 .. [1] NIST Digital Library of Mathematical Functions
12632 https://dlmf.nist.gov/11
12634 Examples
12635 --------
12636 Calculate the Struve function of order 1 at 2.
12638 >>> import numpy as np
12639 >>> from scipy.special import struve
12640 >>> import matplotlib.pyplot as plt
12641 >>> struve(1, 2.)
12642 0.6467637282835622
12644 Calculate the Struve function at 2 for orders 1, 2 and 3 by providing
12645 a list for the order parameter `v`.
12647 >>> struve([1, 2, 3], 2.)
12648 array([0.64676373, 0.28031806, 0.08363767])
12650 Calculate the Struve function of order 1 for several points by providing
12651 an array for `x`.
12653 >>> points = np.array([2., 5., 8.])
12654 >>> struve(1, points)
12655 array([0.64676373, 0.80781195, 0.48811605])
12657 Compute the Struve function for several orders at several points by
12658 providing arrays for `v` and `z`. The arrays have to be broadcastable
12659 to the correct shapes.
12661 >>> orders = np.array([[1], [2], [3]])
12662 >>> points.shape, orders.shape
12663 ((3,), (3, 1))
12665 >>> struve(orders, points)
12666 array([[0.64676373, 0.80781195, 0.48811605],
12667 [0.28031806, 1.56937455, 1.51769363],
12668 [0.08363767, 1.50872065, 2.98697513]])
12670 Plot the Struve functions of order 0 to 3 from -10 to 10.
12672 >>> fig, ax = plt.subplots()
12673 >>> x = np.linspace(-10., 10., 1000)
12674 >>> for i in range(4):
12675 ... ax.plot(x, struve(i, x), label=f'$H_{i!r}$')
12676 >>> ax.legend(ncol=2)
12677 >>> ax.set_xlim(-10, 10)
12678 >>> ax.set_title(r"Struve functions $H_{\nu}$")
12679 >>> plt.show()
12680 """)
12682add_newdoc("tandg",
12683 """
12684 tandg(x, out=None)
12686 Tangent of angle `x` given in degrees.
12688 Parameters
12689 ----------
12690 x : array_like
12691 Angle, given in degrees.
12692 out : ndarray, optional
12693 Optional output array for the function results.
12695 Returns
12696 -------
12697 scalar or ndarray
12698 Tangent at the input.
12700 See Also
12701 --------
12702 sindg, cosdg, cotdg
12704 Examples
12705 --------
12706 >>> import numpy as np
12707 >>> import scipy.special as sc
12709 It is more accurate than using tangent directly.
12711 >>> x = 180 * np.arange(3)
12712 >>> sc.tandg(x)
12713 array([0., 0., 0.])
12714 >>> np.tan(x * np.pi / 180)
12715 array([ 0.0000000e+00, -1.2246468e-16, -2.4492936e-16])
12717 """)
12719add_newdoc("tklmbda",
12720 """
12721 tklmbda(x, lmbda, out=None)
12723 Tukey-Lambda cumulative distribution function
12725 Parameters
12726 ----------
12727 x, lmbda : array_like
12728 Parameters
12729 out : ndarray, optional
12730 Optional output array for the function results
12732 Returns
12733 -------
12734 cdf : scalar or ndarray
12735 Value of the Tukey-Lambda CDF
12736 """)
12738add_newdoc("wofz",
12739 """
12740 wofz(z, out=None)
12742 Faddeeva function
12744 Returns the value of the Faddeeva function for complex argument::
12746 exp(-z**2) * erfc(-i*z)
12748 Parameters
12749 ----------
12750 z : array_like
12751 complex argument
12752 out : ndarray, optional
12753 Optional output array for the function results
12755 Returns
12756 -------
12757 scalar or ndarray
12758 Value of the Faddeeva function
12760 See Also
12761 --------
12762 dawsn, erf, erfc, erfcx, erfi
12764 References
12765 ----------
12766 .. [1] Steven G. Johnson, Faddeeva W function implementation.
12767 http://ab-initio.mit.edu/Faddeeva
12769 Examples
12770 --------
12771 >>> import numpy as np
12772 >>> from scipy import special
12773 >>> import matplotlib.pyplot as plt
12775 >>> x = np.linspace(-3, 3)
12776 >>> z = special.wofz(x)
12778 >>> plt.plot(x, z.real, label='wofz(x).real')
12779 >>> plt.plot(x, z.imag, label='wofz(x).imag')
12780 >>> plt.xlabel('$x$')
12781 >>> plt.legend(framealpha=1, shadow=True)
12782 >>> plt.grid(alpha=0.25)
12783 >>> plt.show()
12785 """)
12787add_newdoc("xlogy",
12788 """
12789 xlogy(x, y, out=None)
12791 Compute ``x*log(y)`` so that the result is 0 if ``x = 0``.
12793 Parameters
12794 ----------
12795 x : array_like
12796 Multiplier
12797 y : array_like
12798 Argument
12799 out : ndarray, optional
12800 Optional output array for the function results
12802 Returns
12803 -------
12804 z : scalar or ndarray
12805 Computed x*log(y)
12807 Notes
12808 -----
12810 .. versionadded:: 0.13.0
12812 """)
12814add_newdoc("xlog1py",
12815 """
12816 xlog1py(x, y, out=None)
12818 Compute ``x*log1p(y)`` so that the result is 0 if ``x = 0``.
12820 Parameters
12821 ----------
12822 x : array_like
12823 Multiplier
12824 y : array_like
12825 Argument
12826 out : ndarray, optional
12827 Optional output array for the function results
12829 Returns
12830 -------
12831 z : scalar or ndarray
12832 Computed x*log1p(y)
12834 Notes
12835 -----
12837 .. versionadded:: 0.13.0
12839 """)
12841add_newdoc("y0",
12842 r"""
12843 y0(x, out=None)
12845 Bessel function of the second kind of order 0.
12847 Parameters
12848 ----------
12849 x : array_like
12850 Argument (float).
12851 out : ndarray, optional
12852 Optional output array for the function results
12854 Returns
12855 -------
12856 Y : scalar or ndarray
12857 Value of the Bessel function of the second kind of order 0 at `x`.
12859 Notes
12860 -----
12862 The domain is divided into the intervals [0, 5] and (5, infinity). In the
12863 first interval a rational approximation :math:`R(x)` is employed to
12864 compute,
12866 .. math::
12868 Y_0(x) = R(x) + \frac{2 \log(x) J_0(x)}{\pi},
12870 where :math:`J_0` is the Bessel function of the first kind of order 0.
12872 In the second interval, the Hankel asymptotic expansion is employed with
12873 two rational functions of degree 6/6 and 7/7.
12875 This function is a wrapper for the Cephes [1]_ routine `y0`.
12877 See also
12878 --------
12879 j0: Bessel function of the first kind of order 0
12880 yv: Bessel function of the first kind
12882 References
12883 ----------
12884 .. [1] Cephes Mathematical Functions Library,
12885 http://www.netlib.org/cephes/
12887 Examples
12888 --------
12889 Calculate the function at one point:
12891 >>> from scipy.special import y0
12892 >>> y0(1.)
12893 0.08825696421567697
12895 Calculate at several points:
12897 >>> import numpy as np
12898 >>> y0(np.array([0.5, 2., 3.]))
12899 array([-0.44451873, 0.51037567, 0.37685001])
12901 Plot the function from 0 to 10.
12903 >>> import matplotlib.pyplot as plt
12904 >>> fig, ax = plt.subplots()
12905 >>> x = np.linspace(0., 10., 1000)
12906 >>> y = y0(x)
12907 >>> ax.plot(x, y)
12908 >>> plt.show()
12910 """)
12912add_newdoc("y1",
12913 """
12914 y1(x, out=None)
12916 Bessel function of the second kind of order 1.
12918 Parameters
12919 ----------
12920 x : array_like
12921 Argument (float).
12922 out : ndarray, optional
12923 Optional output array for the function results
12925 Returns
12926 -------
12927 Y : scalar or ndarray
12928 Value of the Bessel function of the second kind of order 1 at `x`.
12930 Notes
12931 -----
12933 The domain is divided into the intervals [0, 8] and (8, infinity). In the
12934 first interval a 25 term Chebyshev expansion is used, and computing
12935 :math:`J_1` (the Bessel function of the first kind) is required. In the
12936 second, the asymptotic trigonometric representation is employed using two
12937 rational functions of degree 5/5.
12939 This function is a wrapper for the Cephes [1]_ routine `y1`.
12941 See also
12942 --------
12943 j1: Bessel function of the first kind of order 1
12944 yn: Bessel function of the second kind
12945 yv: Bessel function of the second kind
12947 References
12948 ----------
12949 .. [1] Cephes Mathematical Functions Library,
12950 http://www.netlib.org/cephes/
12952 Examples
12953 --------
12954 Calculate the function at one point:
12956 >>> from scipy.special import y1
12957 >>> y1(1.)
12958 -0.7812128213002888
12960 Calculate at several points:
12962 >>> import numpy as np
12963 >>> y1(np.array([0.5, 2., 3.]))
12964 array([-1.47147239, -0.10703243, 0.32467442])
12966 Plot the function from 0 to 10.
12968 >>> import matplotlib.pyplot as plt
12969 >>> fig, ax = plt.subplots()
12970 >>> x = np.linspace(0., 10., 1000)
12971 >>> y = y1(x)
12972 >>> ax.plot(x, y)
12973 >>> plt.show()
12975 """)
12977add_newdoc("yn",
12978 r"""
12979 yn(n, x, out=None)
12981 Bessel function of the second kind of integer order and real argument.
12983 Parameters
12984 ----------
12985 n : array_like
12986 Order (integer).
12987 x : array_like
12988 Argument (float).
12989 out : ndarray, optional
12990 Optional output array for the function results
12992 Returns
12993 -------
12994 Y : scalar or ndarray
12995 Value of the Bessel function, :math:`Y_n(x)`.
12997 Notes
12998 -----
12999 Wrapper for the Cephes [1]_ routine `yn`.
13001 The function is evaluated by forward recurrence on `n`, starting with
13002 values computed by the Cephes routines `y0` and `y1`. If `n = 0` or 1,
13003 the routine for `y0` or `y1` is called directly.
13005 See also
13006 --------
13007 yv : For real order and real or complex argument.
13008 y0: faster implementation of this function for order 0
13009 y1: faster implementation of this function for order 1
13011 References
13012 ----------
13013 .. [1] Cephes Mathematical Functions Library,
13014 http://www.netlib.org/cephes/
13016 Examples
13017 --------
13018 Evaluate the function of order 0 at one point.
13020 >>> from scipy.special import yn
13021 >>> yn(0, 1.)
13022 0.08825696421567697
13024 Evaluate the function at one point for different orders.
13026 >>> yn(0, 1.), yn(1, 1.), yn(2, 1.)
13027 (0.08825696421567697, -0.7812128213002888, -1.6506826068162546)
13029 The evaluation for different orders can be carried out in one call by
13030 providing a list or NumPy array as argument for the `v` parameter:
13032 >>> yn([0, 1, 2], 1.)
13033 array([ 0.08825696, -0.78121282, -1.65068261])
13035 Evaluate the function at several points for order 0 by providing an
13036 array for `z`.
13038 >>> import numpy as np
13039 >>> points = np.array([0.5, 3., 8.])
13040 >>> yn(0, points)
13041 array([-0.44451873, 0.37685001, 0.22352149])
13043 If `z` is an array, the order parameter `v` must be broadcastable to
13044 the correct shape if different orders shall be computed in one call.
13045 To calculate the orders 0 and 1 for an 1D array:
13047 >>> orders = np.array([[0], [1]])
13048 >>> orders.shape
13049 (2, 1)
13051 >>> yn(orders, points)
13052 array([[-0.44451873, 0.37685001, 0.22352149],
13053 [-1.47147239, 0.32467442, -0.15806046]])
13055 Plot the functions of order 0 to 3 from 0 to 10.
13057 >>> import matplotlib.pyplot as plt
13058 >>> fig, ax = plt.subplots()
13059 >>> x = np.linspace(0., 10., 1000)
13060 >>> for i in range(4):
13061 ... ax.plot(x, yn(i, x), label=f'$Y_{i!r}$')
13062 >>> ax.set_ylim(-3, 1)
13063 >>> ax.legend()
13064 >>> plt.show()
13065 """)
13067add_newdoc("yv",
13068 r"""
13069 yv(v, z, out=None)
13071 Bessel function of the second kind of real order and complex argument.
13073 Parameters
13074 ----------
13075 v : array_like
13076 Order (float).
13077 z : array_like
13078 Argument (float or complex).
13079 out : ndarray, optional
13080 Optional output array for the function results
13082 Returns
13083 -------
13084 Y : scalar or ndarray
13085 Value of the Bessel function of the second kind, :math:`Y_v(x)`.
13087 Notes
13088 -----
13089 For positive `v` values, the computation is carried out using the
13090 AMOS [1]_ `zbesy` routine, which exploits the connection to the Hankel
13091 Bessel functions :math:`H_v^{(1)}` and :math:`H_v^{(2)}`,
13093 .. math:: Y_v(z) = \frac{1}{2\imath} (H_v^{(1)} - H_v^{(2)}).
13095 For negative `v` values the formula,
13097 .. math:: Y_{-v}(z) = Y_v(z) \cos(\pi v) + J_v(z) \sin(\pi v)
13099 is used, where :math:`J_v(z)` is the Bessel function of the first kind,
13100 computed using the AMOS routine `zbesj`. Note that the second term is
13101 exactly zero for integer `v`; to improve accuracy the second term is
13102 explicitly omitted for `v` values such that `v = floor(v)`.
13104 See also
13105 --------
13106 yve : :math:`Y_v` with leading exponential behavior stripped off.
13107 y0: faster implementation of this function for order 0
13108 y1: faster implementation of this function for order 1
13110 References
13111 ----------
13112 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
13113 of a Complex Argument and Nonnegative Order",
13114 http://netlib.org/amos/
13116 Examples
13117 --------
13118 Evaluate the function of order 0 at one point.
13120 >>> from scipy.special import yv
13121 >>> yv(0, 1.)
13122 0.088256964215677
13124 Evaluate the function at one point for different orders.
13126 >>> yv(0, 1.), yv(1, 1.), yv(1.5, 1.)
13127 (0.088256964215677, -0.7812128213002889, -1.102495575160179)
13129 The evaluation for different orders can be carried out in one call by
13130 providing a list or NumPy array as argument for the `v` parameter:
13132 >>> yv([0, 1, 1.5], 1.)
13133 array([ 0.08825696, -0.78121282, -1.10249558])
13135 Evaluate the function at several points for order 0 by providing an
13136 array for `z`.
13138 >>> import numpy as np
13139 >>> points = np.array([0.5, 3., 8.])
13140 >>> yv(0, points)
13141 array([-0.44451873, 0.37685001, 0.22352149])
13143 If `z` is an array, the order parameter `v` must be broadcastable to
13144 the correct shape if different orders shall be computed in one call.
13145 To calculate the orders 0 and 1 for an 1D array:
13147 >>> orders = np.array([[0], [1]])
13148 >>> orders.shape
13149 (2, 1)
13151 >>> yv(orders, points)
13152 array([[-0.44451873, 0.37685001, 0.22352149],
13153 [-1.47147239, 0.32467442, -0.15806046]])
13155 Plot the functions of order 0 to 3 from 0 to 10.
13157 >>> import matplotlib.pyplot as plt
13158 >>> fig, ax = plt.subplots()
13159 >>> x = np.linspace(0., 10., 1000)
13160 >>> for i in range(4):
13161 ... ax.plot(x, yv(i, x), label=f'$Y_{i!r}$')
13162 >>> ax.set_ylim(-3, 1)
13163 >>> ax.legend()
13164 >>> plt.show()
13166 """)
13168add_newdoc("yve",
13169 r"""
13170 yve(v, z, out=None)
13172 Exponentially scaled Bessel function of the second kind of real order.
13174 Returns the exponentially scaled Bessel function of the second
13175 kind of real order `v` at complex `z`::
13177 yve(v, z) = yv(v, z) * exp(-abs(z.imag))
13179 Parameters
13180 ----------
13181 v : array_like
13182 Order (float).
13183 z : array_like
13184 Argument (float or complex).
13185 out : ndarray, optional
13186 Optional output array for the function results
13188 Returns
13189 -------
13190 Y : scalar or ndarray
13191 Value of the exponentially scaled Bessel function.
13193 See Also
13194 --------
13195 yv: Unscaled Bessel function of the second kind of real order.
13197 Notes
13198 -----
13199 For positive `v` values, the computation is carried out using the
13200 AMOS [1]_ `zbesy` routine, which exploits the connection to the Hankel
13201 Bessel functions :math:`H_v^{(1)}` and :math:`H_v^{(2)}`,
13203 .. math:: Y_v(z) = \frac{1}{2\imath} (H_v^{(1)} - H_v^{(2)}).
13205 For negative `v` values the formula,
13207 .. math:: Y_{-v}(z) = Y_v(z) \cos(\pi v) + J_v(z) \sin(\pi v)
13209 is used, where :math:`J_v(z)` is the Bessel function of the first kind,
13210 computed using the AMOS routine `zbesj`. Note that the second term is
13211 exactly zero for integer `v`; to improve accuracy the second term is
13212 explicitly omitted for `v` values such that `v = floor(v)`.
13214 Exponentially scaled Bessel functions are useful for large `z`:
13215 for these, the unscaled Bessel functions can easily under-or overflow.
13217 References
13218 ----------
13219 .. [1] Donald E. Amos, "AMOS, A Portable Package for Bessel Functions
13220 of a Complex Argument and Nonnegative Order",
13221 http://netlib.org/amos/
13223 Examples
13224 --------
13225 Compare the output of `yv` and `yve` for large complex arguments for `z`
13226 by computing their values for order ``v=1`` at ``z=1000j``. We see that
13227 `yv` returns nan but `yve` returns a finite number:
13229 >>> import numpy as np
13230 >>> from scipy.special import yv, yve
13231 >>> v = 1
13232 >>> z = 1000j
13233 >>> yv(v, z), yve(v, z)
13234 ((nan+nanj), (-0.012610930256928629+7.721967686709076e-19j))
13236 For real arguments for `z`, `yve` returns the same as `yv` up to
13237 floating point errors.
13239 >>> v, z = 1, 1000
13240 >>> yv(v, z), yve(v, z)
13241 (-0.02478433129235178, -0.02478433129235179)
13243 The function can be evaluated for several orders at the same time by
13244 providing a list or NumPy array for `v`:
13246 >>> yve([1, 2, 3], 1j)
13247 array([-0.20791042+0.14096627j, 0.38053618-0.04993878j,
13248 0.00815531-1.66311097j])
13250 In the same way, the function can be evaluated at several points in one
13251 call by providing a list or NumPy array for `z`:
13253 >>> yve(1, np.array([1j, 2j, 3j]))
13254 array([-0.20791042+0.14096627j, -0.21526929+0.01205044j,
13255 -0.19682671+0.00127278j])
13257 It is also possible to evaluate several orders at several points
13258 at the same time by providing arrays for `v` and `z` with
13259 broadcasting compatible shapes. Compute `yve` for two different orders
13260 `v` and three points `z` resulting in a 2x3 array.
13262 >>> v = np.array([[1], [2]])
13263 >>> z = np.array([3j, 4j, 5j])
13264 >>> v.shape, z.shape
13265 ((2, 1), (3,))
13267 >>> yve(v, z)
13268 array([[-1.96826713e-01+1.27277544e-03j, -1.78750840e-01+1.45558819e-04j,
13269 -1.63972267e-01+1.73494110e-05j],
13270 [1.94960056e-03-1.11782545e-01j, 2.02902325e-04-1.17626501e-01j,
13271 2.27727687e-05-1.17951906e-01j]])
13272 """)
13274add_newdoc("_zeta",
13275 """
13276 _zeta(x, q)
13278 Internal function, Hurwitz zeta.
13280 """)
13282add_newdoc("zetac",
13283 """
13284 zetac(x, out=None)
13286 Riemann zeta function minus 1.
13288 This function is defined as
13290 .. math:: \\zeta(x) = \\sum_{k=2}^{\\infty} 1 / k^x,
13292 where ``x > 1``. For ``x < 1`` the analytic continuation is
13293 computed. For more information on the Riemann zeta function, see
13294 [dlmf]_.
13296 Parameters
13297 ----------
13298 x : array_like of float
13299 Values at which to compute zeta(x) - 1 (must be real).
13300 out : ndarray, optional
13301 Optional output array for the function results
13303 Returns
13304 -------
13305 scalar or ndarray
13306 Values of zeta(x) - 1.
13308 See Also
13309 --------
13310 zeta
13312 Examples
13313 --------
13314 >>> import numpy as np
13315 >>> from scipy.special import zetac, zeta
13317 Some special values:
13319 >>> zetac(2), np.pi**2/6 - 1
13320 (0.64493406684822641, 0.6449340668482264)
13322 >>> zetac(-1), -1.0/12 - 1
13323 (-1.0833333333333333, -1.0833333333333333)
13325 Compare ``zetac(x)`` to ``zeta(x) - 1`` for large `x`:
13327 >>> zetac(60), zeta(60) - 1
13328 (8.673617380119933e-19, 0.0)
13330 References
13331 ----------
13332 .. [dlmf] NIST Digital Library of Mathematical Functions
13333 https://dlmf.nist.gov/25
13335 """)
13337add_newdoc("_riemann_zeta",
13338 """
13339 Internal function, use `zeta` instead.
13340 """)
13342add_newdoc("_struve_asymp_large_z",
13343 """
13344 _struve_asymp_large_z(v, z, is_h)
13346 Internal function for testing `struve` & `modstruve`
13348 Evaluates using asymptotic expansion
13350 Returns
13351 -------
13352 v, err
13353 """)
13355add_newdoc("_struve_power_series",
13356 """
13357 _struve_power_series(v, z, is_h)
13359 Internal function for testing `struve` & `modstruve`
13361 Evaluates using power series
13363 Returns
13364 -------
13365 v, err
13366 """)
13368add_newdoc("_struve_bessel_series",
13369 """
13370 _struve_bessel_series(v, z, is_h)
13372 Internal function for testing `struve` & `modstruve`
13374 Evaluates using Bessel function series
13376 Returns
13377 -------
13378 v, err
13379 """)
13381add_newdoc("_spherical_jn",
13382 """
13383 Internal function, use `spherical_jn` instead.
13384 """)
13386add_newdoc("_spherical_jn_d",
13387 """
13388 Internal function, use `spherical_jn` instead.
13389 """)
13391add_newdoc("_spherical_yn",
13392 """
13393 Internal function, use `spherical_yn` instead.
13394 """)
13396add_newdoc("_spherical_yn_d",
13397 """
13398 Internal function, use `spherical_yn` instead.
13399 """)
13401add_newdoc("_spherical_in",
13402 """
13403 Internal function, use `spherical_in` instead.
13404 """)
13406add_newdoc("_spherical_in_d",
13407 """
13408 Internal function, use `spherical_in` instead.
13409 """)
13411add_newdoc("_spherical_kn",
13412 """
13413 Internal function, use `spherical_kn` instead.
13414 """)
13416add_newdoc("_spherical_kn_d",
13417 """
13418 Internal function, use `spherical_kn` instead.
13419 """)
13421add_newdoc("loggamma",
13422 r"""
13423 loggamma(z, out=None)
13425 Principal branch of the logarithm of the gamma function.
13427 Defined to be :math:`\log(\Gamma(x))` for :math:`x > 0` and
13428 extended to the complex plane by analytic continuation. The
13429 function has a single branch cut on the negative real axis.
13431 .. versionadded:: 0.18.0
13433 Parameters
13434 ----------
13435 z : array_like
13436 Values in the complex plain at which to compute ``loggamma``
13437 out : ndarray, optional
13438 Output array for computed values of ``loggamma``
13440 Returns
13441 -------
13442 loggamma : scalar or ndarray
13443 Values of ``loggamma`` at z.
13445 Notes
13446 -----
13447 It is not generally true that :math:`\log\Gamma(z) =
13448 \log(\Gamma(z))`, though the real parts of the functions do
13449 agree. The benefit of not defining `loggamma` as
13450 :math:`\log(\Gamma(z))` is that the latter function has a
13451 complicated branch cut structure whereas `loggamma` is analytic
13452 except for on the negative real axis.
13454 The identities
13456 .. math::
13457 \exp(\log\Gamma(z)) &= \Gamma(z) \\
13458 \log\Gamma(z + 1) &= \log(z) + \log\Gamma(z)
13460 make `loggamma` useful for working in complex logspace.
13462 On the real line `loggamma` is related to `gammaln` via
13463 ``exp(loggamma(x + 0j)) = gammasgn(x)*exp(gammaln(x))``, up to
13464 rounding error.
13466 The implementation here is based on [hare1997]_.
13468 See also
13469 --------
13470 gammaln : logarithm of the absolute value of the gamma function
13471 gammasgn : sign of the gamma function
13473 References
13474 ----------
13475 .. [hare1997] D.E.G. Hare,
13476 *Computing the Principal Branch of log-Gamma*,
13477 Journal of Algorithms, Volume 25, Issue 2, November 1997, pages 221-236.
13478 """)
13480add_newdoc("_sinpi",
13481 """
13482 Internal function, do not use.
13483 """)
13485add_newdoc("_cospi",
13486 """
13487 Internal function, do not use.
13488 """)
13490add_newdoc("owens_t",
13491 """
13492 owens_t(h, a, out=None)
13494 Owen's T Function.
13496 The function T(h, a) gives the probability of the event
13497 (X > h and 0 < Y < a * X) where X and Y are independent
13498 standard normal random variables.
13500 Parameters
13501 ----------
13502 h: array_like
13503 Input value.
13504 a: array_like
13505 Input value.
13506 out : ndarray, optional
13507 Optional output array for the function results
13509 Returns
13510 -------
13511 t: scalar or ndarray
13512 Probability of the event (X > h and 0 < Y < a * X),
13513 where X and Y are independent standard normal random variables.
13515 Examples
13516 --------
13517 >>> from scipy import special
13518 >>> a = 3.5
13519 >>> h = 0.78
13520 >>> special.owens_t(h, a)
13521 0.10877216734852274
13523 References
13524 ----------
13525 .. [1] M. Patefield and D. Tandy, "Fast and accurate calculation of
13526 Owen's T Function", Statistical Software vol. 5, pp. 1-25, 2000.
13527 """)
13529add_newdoc("_factorial",
13530 """
13531 Internal function, do not use.
13532 """)
13534add_newdoc("wright_bessel",
13535 r"""
13536 wright_bessel(a, b, x, out=None)
13538 Wright's generalized Bessel function.
13540 Wright's generalized Bessel function is an entire function and defined as
13542 .. math:: \Phi(a, b; x) = \sum_{k=0}^\infty \frac{x^k}{k! \Gamma(a k + b)}
13544 See also [1].
13546 Parameters
13547 ----------
13548 a : array_like of float
13549 a >= 0
13550 b : array_like of float
13551 b >= 0
13552 x : array_like of float
13553 x >= 0
13554 out : ndarray, optional
13555 Optional output array for the function results
13557 Returns
13558 -------
13559 scalar or ndarray
13560 Value of the Wright's generalized Bessel function
13562 Notes
13563 -----
13564 Due to the compexity of the function with its three parameters, only
13565 non-negative arguments are implemented.
13567 Examples
13568 --------
13569 >>> from scipy.special import wright_bessel
13570 >>> a, b, x = 1.5, 1.1, 2.5
13571 >>> wright_bessel(a, b-1, x)
13572 4.5314465939443025
13574 Now, let us verify the relation
13576 .. math:: \Phi(a, b-1; x) = a x \Phi(a, b+a; x) + (b-1) \Phi(a, b; x)
13578 >>> a * x * wright_bessel(a, b+a, x) + (b-1) * wright_bessel(a, b, x)
13579 4.5314465939443025
13581 References
13582 ----------
13583 .. [1] Digital Library of Mathematical Functions, 10.46.
13584 https://dlmf.nist.gov/10.46.E1
13585 """)
13588add_newdoc("ndtri_exp",
13589 r"""
13590 ndtri_exp(y, out=None)
13592 Inverse of `log_ndtr` vs x. Allows for greater precision than
13593 `ndtri` composed with `numpy.exp` for very small values of y and for
13594 y close to 0.
13596 Parameters
13597 ----------
13598 y : array_like of float
13599 Function argument
13600 out : ndarray, optional
13601 Optional output array for the function results
13603 Returns
13604 -------
13605 scalar or ndarray
13606 Inverse of the log CDF of the standard normal distribution, evaluated
13607 at y.
13609 Examples
13610 --------
13611 >>> import numpy as np
13612 >>> import scipy.special as sc
13614 `ndtri_exp` agrees with the naive implementation when the latter does
13615 not suffer from underflow.
13617 >>> sc.ndtri_exp(-1)
13618 -0.33747496376420244
13619 >>> sc.ndtri(np.exp(-1))
13620 -0.33747496376420244
13622 For extreme values of y, the naive approach fails
13624 >>> sc.ndtri(np.exp(-800))
13625 -inf
13626 >>> sc.ndtri(np.exp(-1e-20))
13627 inf
13629 whereas `ndtri_exp` is still able to compute the result to high precision.
13631 >>> sc.ndtri_exp(-800)
13632 -39.88469483825668
13633 >>> sc.ndtri_exp(-1e-20)
13634 9.262340089798409
13636 See Also
13637 --------
13638 log_ndtr, ndtri, ndtr
13639 """)