Coverage for /usr/lib/python3/dist-packages/mpmath/function_docs.py: 100%
184 statements
« prev ^ index » next coverage.py v7.9.1, created at 2025-06-14 15:55 +0200
1"""
2Extended docstrings for functions.py
3"""
6pi = r"""
7`\pi`, roughly equal to 3.141592654, represents the area of the unit
8circle, the half-period of trigonometric functions, and many other
9things in mathematics.
11Mpmath can evaluate `\pi` to arbitrary precision::
13 >>> from mpmath import *
14 >>> mp.dps = 50; mp.pretty = True
15 >>> +pi
16 3.1415926535897932384626433832795028841971693993751
18This shows digits 99991-100000 of `\pi` (the last digit is actually
19a 4 when the decimal expansion is truncated, but here the nearest
20rounding is used)::
22 >>> mp.dps = 100000
23 >>> str(pi)[-10:]
24 '5549362465'
26**Possible issues**
28:data:`pi` always rounds to the nearest floating-point
29number when used. This means that exact mathematical identities
30involving `\pi` will generally not be preserved in floating-point
31arithmetic. In particular, multiples of :data:`pi` (except for
32the trivial case ``0*pi``) are *not* the exact roots of
33:func:`~mpmath.sin`, but differ roughly by the current epsilon::
35 >>> mp.dps = 15
36 >>> sin(pi)
37 1.22464679914735e-16
39One solution is to use the :func:`~mpmath.sinpi` function instead::
41 >>> sinpi(1)
42 0.0
44See the documentation of trigonometric functions for additional
45details.
46"""
48degree = r"""
49Represents one degree of angle, `1^{\circ} = \pi/180`, or
50about 0.01745329. This constant may be evaluated to arbitrary
51precision::
53 >>> from mpmath import *
54 >>> mp.dps = 50; mp.pretty = True
55 >>> +degree
56 0.017453292519943295769236907684886127134428718885417
58The :data:`degree` object is convenient for conversion
59to radians::
61 >>> sin(30 * degree)
62 0.5
63 >>> asin(0.5) / degree
64 30.0
65"""
67e = r"""
68The transcendental number `e` = 2.718281828... is the base of the
69natural logarithm (:func:`~mpmath.ln`) and of the exponential function
70(:func:`~mpmath.exp`).
72Mpmath can be evaluate `e` to arbitrary precision::
74 >>> from mpmath import *
75 >>> mp.dps = 50; mp.pretty = True
76 >>> +e
77 2.7182818284590452353602874713526624977572470937
79This shows digits 99991-100000 of `e` (the last digit is actually
80a 5 when the decimal expansion is truncated, but here the nearest
81rounding is used)::
83 >>> mp.dps = 100000
84 >>> str(e)[-10:]
85 '2100427166'
87**Possible issues**
89:data:`e` always rounds to the nearest floating-point number
90when used, and mathematical identities involving `e` may not
91hold in floating-point arithmetic. For example, ``ln(e)``
92might not evaluate exactly to 1.
94In particular, don't use ``e**x`` to compute the exponential
95function. Use ``exp(x)`` instead; this is both faster and more
96accurate.
97"""
99phi = r"""
100Represents the golden ratio `\phi = (1+\sqrt 5)/2`,
101approximately equal to 1.6180339887. To high precision,
102its value is::
104 >>> from mpmath import *
105 >>> mp.dps = 50; mp.pretty = True
106 >>> +phi
107 1.6180339887498948482045868343656381177203091798058
109Formulas for the golden ratio include the following::
111 >>> (1+sqrt(5))/2
112 1.6180339887498948482045868343656381177203091798058
113 >>> findroot(lambda x: x**2-x-1, 1)
114 1.6180339887498948482045868343656381177203091798058
115 >>> limit(lambda n: fib(n+1)/fib(n), inf)
116 1.6180339887498948482045868343656381177203091798058
117"""
119euler = r"""
120Euler's constant or the Euler-Mascheroni constant `\gamma`
121= 0.57721566... is a number of central importance to
122number theory and special functions. It is defined as the limit
124.. math ::
126 \gamma = \lim_{n\to\infty} H_n - \log n
128where `H_n = 1 + \frac{1}{2} + \ldots + \frac{1}{n}` is a harmonic
129number (see :func:`~mpmath.harmonic`).
131Evaluation of `\gamma` is supported at arbitrary precision::
133 >>> from mpmath import *
134 >>> mp.dps = 50; mp.pretty = True
135 >>> +euler
136 0.57721566490153286060651209008240243104215933593992
138We can also compute `\gamma` directly from the definition,
139although this is less efficient::
141 >>> limit(lambda n: harmonic(n)-log(n), inf)
142 0.57721566490153286060651209008240243104215933593992
144This shows digits 9991-10000 of `\gamma` (the last digit is actually
145a 5 when the decimal expansion is truncated, but here the nearest
146rounding is used)::
148 >>> mp.dps = 10000
149 >>> str(euler)[-10:]
150 '4679858166'
152Integrals, series, and representations for `\gamma` in terms of
153special functions include the following (there are many others)::
155 >>> mp.dps = 25
156 >>> -quad(lambda x: exp(-x)*log(x), [0,inf])
157 0.5772156649015328606065121
158 >>> quad(lambda x,y: (x-1)/(1-x*y)/log(x*y), [0,1], [0,1])
159 0.5772156649015328606065121
160 >>> nsum(lambda k: 1/k-log(1+1/k), [1,inf])
161 0.5772156649015328606065121
162 >>> nsum(lambda k: (-1)**k*zeta(k)/k, [2,inf])
163 0.5772156649015328606065121
164 >>> -diff(gamma, 1)
165 0.5772156649015328606065121
166 >>> limit(lambda x: 1/x-gamma(x), 0)
167 0.5772156649015328606065121
168 >>> limit(lambda x: zeta(x)-1/(x-1), 1)
169 0.5772156649015328606065121
170 >>> (log(2*pi*nprod(lambda n:
171 ... exp(-2+2/n)*(1+2/n)**n, [1,inf]))-3)/2
172 0.5772156649015328606065121
174For generalizations of the identities `\gamma = -\Gamma'(1)`
175and `\gamma = \lim_{x\to1} \zeta(x)-1/(x-1)`, see
176:func:`~mpmath.psi` and :func:`~mpmath.stieltjes` respectively.
177"""
179catalan = r"""
180Catalan's constant `K` = 0.91596559... is given by the infinite
181series
183.. math ::
185 K = \sum_{k=0}^{\infty} \frac{(-1)^k}{(2k+1)^2}.
187Mpmath can evaluate it to arbitrary precision::
189 >>> from mpmath import *
190 >>> mp.dps = 50; mp.pretty = True
191 >>> +catalan
192 0.91596559417721901505460351493238411077414937428167
194One can also compute `K` directly from the definition, although
195this is significantly less efficient::
197 >>> nsum(lambda k: (-1)**k/(2*k+1)**2, [0, inf])
198 0.91596559417721901505460351493238411077414937428167
200This shows digits 9991-10000 of `K` (the last digit is actually
201a 3 when the decimal expansion is truncated, but here the nearest
202rounding is used)::
204 >>> mp.dps = 10000
205 >>> str(catalan)[-10:]
206 '9537871504'
208Catalan's constant has numerous integral representations::
210 >>> mp.dps = 50
211 >>> quad(lambda x: -log(x)/(1+x**2), [0, 1])
212 0.91596559417721901505460351493238411077414937428167
213 >>> quad(lambda x: atan(x)/x, [0, 1])
214 0.91596559417721901505460351493238411077414937428167
215 >>> quad(lambda x: ellipk(x**2)/2, [0, 1])
216 0.91596559417721901505460351493238411077414937428167
217 >>> quad(lambda x,y: 1/(1+(x*y)**2), [0, 1], [0, 1])
218 0.91596559417721901505460351493238411077414937428167
220As well as series representations::
222 >>> pi*log(sqrt(3)+2)/8 + 3*nsum(lambda n:
223 ... (fac(n)/(2*n+1))**2/fac(2*n), [0, inf])/8
224 0.91596559417721901505460351493238411077414937428167
225 >>> 1-nsum(lambda n: n*zeta(2*n+1)/16**n, [1,inf])
226 0.91596559417721901505460351493238411077414937428167
227"""
229khinchin = r"""
230Khinchin's constant `K` = 2.68542... is a number that
231appears in the theory of continued fractions. Mpmath can evaluate
232it to arbitrary precision::
234 >>> from mpmath import *
235 >>> mp.dps = 50; mp.pretty = True
236 >>> +khinchin
237 2.6854520010653064453097148354817956938203822939945
239An integral representation is::
241 >>> I = quad(lambda x: log((1-x**2)/sincpi(x))/x/(1+x), [0, 1])
242 >>> 2*exp(1/log(2)*I)
243 2.6854520010653064453097148354817956938203822939945
245The computation of ``khinchin`` is based on an efficient
246implementation of the following series::
248 >>> f = lambda n: (zeta(2*n)-1)/n*sum((-1)**(k+1)/mpf(k)
249 ... for k in range(1,2*int(n)))
250 >>> exp(nsum(f, [1,inf])/log(2))
251 2.6854520010653064453097148354817956938203822939945
252"""
254glaisher = r"""
255Glaisher's constant `A`, also known as the Glaisher-Kinkelin
256constant, is a number approximately equal to 1.282427129 that
257sometimes appears in formulas related to gamma and zeta functions.
258It is also related to the Barnes G-function (see :func:`~mpmath.barnesg`).
260The constant is defined as `A = \exp(1/12-\zeta'(-1))` where
261`\zeta'(s)` denotes the derivative of the Riemann zeta function
262(see :func:`~mpmath.zeta`).
264Mpmath can evaluate Glaisher's constant to arbitrary precision:
266 >>> from mpmath import *
267 >>> mp.dps = 50; mp.pretty = True
268 >>> +glaisher
269 1.282427129100622636875342568869791727767688927325
271We can verify that the value computed by :data:`glaisher` is
272correct using mpmath's facilities for numerical
273differentiation and arbitrary evaluation of the zeta function:
275 >>> exp(mpf(1)/12 - diff(zeta, -1))
276 1.282427129100622636875342568869791727767688927325
278Here is an example of an integral that can be evaluated in
279terms of Glaisher's constant:
281 >>> mp.dps = 15
282 >>> quad(lambda x: log(gamma(x)), [1, 1.5])
283 -0.0428537406502909
284 >>> -0.5 - 7*log(2)/24 + log(pi)/4 + 3*log(glaisher)/2
285 -0.042853740650291
287Mpmath computes Glaisher's constant by applying Euler-Maclaurin
288summation to a slowly convergent series. The implementation is
289reasonably efficient up to about 10,000 digits. See the source
290code for additional details.
292References:
293http://mathworld.wolfram.com/Glaisher-KinkelinConstant.html
294"""
296apery = r"""
297Represents Apery's constant, which is the irrational number
298approximately equal to 1.2020569 given by
300.. math ::
302 \zeta(3) = \sum_{k=1}^\infty\frac{1}{k^3}.
304The calculation is based on an efficient hypergeometric
305series. To 50 decimal places, the value is given by::
307 >>> from mpmath import *
308 >>> mp.dps = 50; mp.pretty = True
309 >>> +apery
310 1.2020569031595942853997381615114499907649862923405
312Other ways to evaluate Apery's constant using mpmath
313include::
315 >>> zeta(3)
316 1.2020569031595942853997381615114499907649862923405
317 >>> -psi(2,1)/2
318 1.2020569031595942853997381615114499907649862923405
319 >>> 8*nsum(lambda k: 1/(2*k+1)**3, [0,inf])/7
320 1.2020569031595942853997381615114499907649862923405
321 >>> f = lambda k: 2/k**3/(exp(2*pi*k)-1)
322 >>> 7*pi**3/180 - nsum(f, [1,inf])
323 1.2020569031595942853997381615114499907649862923405
325This shows digits 9991-10000 of Apery's constant::
327 >>> mp.dps = 10000
328 >>> str(apery)[-10:]
329 '3189504235'
330"""
332mertens = r"""
333Represents the Mertens or Meissel-Mertens constant, which is the
334prime number analog of Euler's constant:
336.. math ::
338 B_1 = \lim_{N\to\infty}
339 \left(\sum_{p_k \le N} \frac{1}{p_k} - \log \log N \right)
341Here `p_k` denotes the `k`-th prime number. Other names for this
342constant include the Hadamard-de la Vallee-Poussin constant or
343the prime reciprocal constant.
345The following gives the Mertens constant to 50 digits::
347 >>> from mpmath import *
348 >>> mp.dps = 50; mp.pretty = True
349 >>> +mertens
350 0.2614972128476427837554268386086958590515666482612
352References:
353http://mathworld.wolfram.com/MertensConstant.html
354"""
356twinprime = r"""
357Represents the twin prime constant, which is the factor `C_2`
358featuring in the Hardy-Littlewood conjecture for the growth of the
359twin prime counting function,
361.. math ::
363 \pi_2(n) \sim 2 C_2 \frac{n}{\log^2 n}.
365It is given by the product over primes
367.. math ::
369 C_2 = \prod_{p\ge3} \frac{p(p-2)}{(p-1)^2} \approx 0.66016
371Computing `C_2` to 50 digits::
373 >>> from mpmath import *
374 >>> mp.dps = 50; mp.pretty = True
375 >>> +twinprime
376 0.66016181584686957392781211001455577843262336028473
378References:
379http://mathworld.wolfram.com/TwinPrimesConstant.html
380"""
382ln = r"""
383Computes the natural logarithm of `x`, `\ln x`.
384See :func:`~mpmath.log` for additional documentation."""
386sqrt = r"""
387``sqrt(x)`` gives the principal square root of `x`, `\sqrt x`.
388For positive real numbers, the principal root is simply the
389positive square root. For arbitrary complex numbers, the principal
390square root is defined to satisfy `\sqrt x = \exp(\log(x)/2)`.
391The function thus has a branch cut along the negative half real axis.
393For all mpmath numbers ``x``, calling ``sqrt(x)`` is equivalent to
394performing ``x**0.5``.
396**Examples**
398Basic examples and limits::
400 >>> from mpmath import *
401 >>> mp.dps = 15; mp.pretty = True
402 >>> sqrt(10)
403 3.16227766016838
404 >>> sqrt(100)
405 10.0
406 >>> sqrt(-4)
407 (0.0 + 2.0j)
408 >>> sqrt(1+1j)
409 (1.09868411346781 + 0.455089860562227j)
410 >>> sqrt(inf)
411 +inf
413Square root evaluation is fast at huge precision::
415 >>> mp.dps = 50000
416 >>> a = sqrt(3)
417 >>> str(a)[-10:]
418 '9329332815'
420:func:`mpmath.iv.sqrt` supports interval arguments::
422 >>> iv.dps = 15; iv.pretty = True
423 >>> iv.sqrt([16,100])
424 [4.0, 10.0]
425 >>> iv.sqrt(2)
426 [1.4142135623730949234, 1.4142135623730951455]
427 >>> iv.sqrt(2) ** 2
428 [1.9999999999999995559, 2.0000000000000004441]
430"""
432cbrt = r"""
433``cbrt(x)`` computes the cube root of `x`, `x^{1/3}`. This
434function is faster and more accurate than raising to a floating-point
435fraction::
437 >>> from mpmath import *
438 >>> mp.dps = 15; mp.pretty = False
439 >>> 125**(mpf(1)/3)
440 mpf('4.9999999999999991')
441 >>> cbrt(125)
442 mpf('5.0')
444Every nonzero complex number has three cube roots. This function
445returns the cube root defined by `\exp(\log(x)/3)` where the
446principal branch of the natural logarithm is used. Note that this
447does not give a real cube root for negative real numbers::
449 >>> mp.pretty = True
450 >>> cbrt(-1)
451 (0.5 + 0.866025403784439j)
452"""
454exp = r"""
455Computes the exponential function,
457.. math ::
459 \exp(x) = e^x = \sum_{k=0}^{\infty} \frac{x^k}{k!}.
461For complex numbers, the exponential function also satisfies
463.. math ::
465 \exp(x+yi) = e^x (\cos y + i \sin y).
467**Basic examples**
469Some values of the exponential function::
471 >>> from mpmath import *
472 >>> mp.dps = 25; mp.pretty = True
473 >>> exp(0)
474 1.0
475 >>> exp(1)
476 2.718281828459045235360287
477 >>> exp(-1)
478 0.3678794411714423215955238
479 >>> exp(inf)
480 +inf
481 >>> exp(-inf)
482 0.0
484Arguments can be arbitrarily large::
486 >>> exp(10000)
487 8.806818225662921587261496e+4342
488 >>> exp(-10000)
489 1.135483865314736098540939e-4343
491Evaluation is supported for interval arguments via
492:func:`mpmath.iv.exp`::
494 >>> iv.dps = 25; iv.pretty = True
495 >>> iv.exp([-inf,0])
496 [0.0, 1.0]
497 >>> iv.exp([0,1])
498 [1.0, 2.71828182845904523536028749558]
500The exponential function can be evaluated efficiently to arbitrary
501precision::
503 >>> mp.dps = 10000
504 >>> exp(pi) #doctest: +ELLIPSIS
505 23.140692632779269005729...8984304016040616
507**Functional properties**
509Numerical verification of Euler's identity for the complex
510exponential function::
512 >>> mp.dps = 15
513 >>> exp(j*pi)+1
514 (0.0 + 1.22464679914735e-16j)
515 >>> chop(exp(j*pi)+1)
516 0.0
518This recovers the coefficients (reciprocal factorials) in the
519Maclaurin series expansion of exp::
521 >>> nprint(taylor(exp, 0, 5))
522 [1.0, 1.0, 0.5, 0.166667, 0.0416667, 0.00833333]
524The exponential function is its own derivative and antiderivative::
526 >>> exp(pi)
527 23.1406926327793
528 >>> diff(exp, pi)
529 23.1406926327793
530 >>> quad(exp, [-inf, pi])
531 23.1406926327793
533The exponential function can be evaluated using various methods,
534including direct summation of the series, limits, and solving
535the defining differential equation::
537 >>> nsum(lambda k: pi**k/fac(k), [0,inf])
538 23.1406926327793
539 >>> limit(lambda k: (1+pi/k)**k, inf)
540 23.1406926327793
541 >>> odefun(lambda t, x: x, 0, 1)(pi)
542 23.1406926327793
543"""
545cosh = r"""
546Computes the hyperbolic cosine of `x`,
547`\cosh(x) = (e^x + e^{-x})/2`. Values and limits include::
549 >>> from mpmath import *
550 >>> mp.dps = 25; mp.pretty = True
551 >>> cosh(0)
552 1.0
553 >>> cosh(1)
554 1.543080634815243778477906
555 >>> cosh(-inf), cosh(+inf)
556 (+inf, +inf)
558The hyperbolic cosine is an even, convex function with
559a global minimum at `x = 0`, having a Maclaurin series
560that starts::
562 >>> nprint(chop(taylor(cosh, 0, 5)))
563 [1.0, 0.0, 0.5, 0.0, 0.0416667, 0.0]
565Generalized to complex numbers, the hyperbolic cosine is
566equivalent to a cosine with the argument rotated
567in the imaginary direction, or `\cosh x = \cos ix`::
569 >>> cosh(2+3j)
570 (-3.724545504915322565473971 + 0.5118225699873846088344638j)
571 >>> cos(3-2j)
572 (-3.724545504915322565473971 + 0.5118225699873846088344638j)
573"""
575sinh = r"""
576Computes the hyperbolic sine of `x`,
577`\sinh(x) = (e^x - e^{-x})/2`. Values and limits include::
579 >>> from mpmath import *
580 >>> mp.dps = 25; mp.pretty = True
581 >>> sinh(0)
582 0.0
583 >>> sinh(1)
584 1.175201193643801456882382
585 >>> sinh(-inf), sinh(+inf)
586 (-inf, +inf)
588The hyperbolic sine is an odd function, with a Maclaurin
589series that starts::
591 >>> nprint(chop(taylor(sinh, 0, 5)))
592 [0.0, 1.0, 0.0, 0.166667, 0.0, 0.00833333]
594Generalized to complex numbers, the hyperbolic sine is
595essentially a sine with a rotation `i` applied to
596the argument; more precisely, `\sinh x = -i \sin ix`::
598 >>> sinh(2+3j)
599 (-3.590564589985779952012565 + 0.5309210862485198052670401j)
600 >>> j*sin(3-2j)
601 (-3.590564589985779952012565 + 0.5309210862485198052670401j)
602"""
604tanh = r"""
605Computes the hyperbolic tangent of `x`,
606`\tanh(x) = \sinh(x)/\cosh(x)`. Values and limits include::
608 >>> from mpmath import *
609 >>> mp.dps = 25; mp.pretty = True
610 >>> tanh(0)
611 0.0
612 >>> tanh(1)
613 0.7615941559557648881194583
614 >>> tanh(-inf), tanh(inf)
615 (-1.0, 1.0)
617The hyperbolic tangent is an odd, sigmoidal function, similar
618to the inverse tangent and error function. Its Maclaurin
619series is::
621 >>> nprint(chop(taylor(tanh, 0, 5)))
622 [0.0, 1.0, 0.0, -0.333333, 0.0, 0.133333]
624Generalized to complex numbers, the hyperbolic tangent is
625essentially a tangent with a rotation `i` applied to
626the argument; more precisely, `\tanh x = -i \tan ix`::
628 >>> tanh(2+3j)
629 (0.9653858790221331242784803 - 0.009884375038322493720314034j)
630 >>> j*tan(3-2j)
631 (0.9653858790221331242784803 - 0.009884375038322493720314034j)
632"""
634cos = r"""
635Computes the cosine of `x`, `\cos(x)`.
637 >>> from mpmath import *
638 >>> mp.dps = 25; mp.pretty = True
639 >>> cos(pi/3)
640 0.5
641 >>> cos(100000001)
642 -0.9802850113244713353133243
643 >>> cos(2+3j)
644 (-4.189625690968807230132555 - 9.109227893755336597979197j)
645 >>> cos(inf)
646 nan
647 >>> nprint(chop(taylor(cos, 0, 6)))
648 [1.0, 0.0, -0.5, 0.0, 0.0416667, 0.0, -0.00138889]
650Intervals are supported via :func:`mpmath.iv.cos`::
652 >>> iv.dps = 25; iv.pretty = True
653 >>> iv.cos([0,1])
654 [0.540302305868139717400936602301, 1.0]
655 >>> iv.cos([0,2])
656 [-0.41614683654714238699756823214, 1.0]
657"""
659sin = r"""
660Computes the sine of `x`, `\sin(x)`.
662 >>> from mpmath import *
663 >>> mp.dps = 25; mp.pretty = True
664 >>> sin(pi/3)
665 0.8660254037844386467637232
666 >>> sin(100000001)
667 0.1975887055794968911438743
668 >>> sin(2+3j)
669 (9.1544991469114295734673 - 4.168906959966564350754813j)
670 >>> sin(inf)
671 nan
672 >>> nprint(chop(taylor(sin, 0, 6)))
673 [0.0, 1.0, 0.0, -0.166667, 0.0, 0.00833333, 0.0]
675Intervals are supported via :func:`mpmath.iv.sin`::
677 >>> iv.dps = 25; iv.pretty = True
678 >>> iv.sin([0,1])
679 [0.0, 0.841470984807896506652502331201]
680 >>> iv.sin([0,2])
681 [0.0, 1.0]
682"""
684tan = r"""
685Computes the tangent of `x`, `\tan(x) = \frac{\sin(x)}{\cos(x)}`.
686The tangent function is singular at `x = (n+1/2)\pi`, but
687``tan(x)`` always returns a finite result since `(n+1/2)\pi`
688cannot be represented exactly using floating-point arithmetic.
690 >>> from mpmath import *
691 >>> mp.dps = 25; mp.pretty = True
692 >>> tan(pi/3)
693 1.732050807568877293527446
694 >>> tan(100000001)
695 -0.2015625081449864533091058
696 >>> tan(2+3j)
697 (-0.003764025641504248292751221 + 1.003238627353609801446359j)
698 >>> tan(inf)
699 nan
700 >>> nprint(chop(taylor(tan, 0, 6)))
701 [0.0, 1.0, 0.0, 0.333333, 0.0, 0.133333, 0.0]
703Intervals are supported via :func:`mpmath.iv.tan`::
705 >>> iv.dps = 25; iv.pretty = True
706 >>> iv.tan([0,1])
707 [0.0, 1.55740772465490223050697482944]
708 >>> iv.tan([0,2]) # Interval includes a singularity
709 [-inf, +inf]
710"""
712sec = r"""
713Computes the secant of `x`, `\mathrm{sec}(x) = \frac{1}{\cos(x)}`.
714The secant function is singular at `x = (n+1/2)\pi`, but
715``sec(x)`` always returns a finite result since `(n+1/2)\pi`
716cannot be represented exactly using floating-point arithmetic.
718 >>> from mpmath import *
719 >>> mp.dps = 25; mp.pretty = True
720 >>> sec(pi/3)
721 2.0
722 >>> sec(10000001)
723 -1.184723164360392819100265
724 >>> sec(2+3j)
725 (-0.04167496441114427004834991 + 0.0906111371962375965296612j)
726 >>> sec(inf)
727 nan
728 >>> nprint(chop(taylor(sec, 0, 6)))
729 [1.0, 0.0, 0.5, 0.0, 0.208333, 0.0, 0.0847222]
731Intervals are supported via :func:`mpmath.iv.sec`::
733 >>> iv.dps = 25; iv.pretty = True
734 >>> iv.sec([0,1])
735 [1.0, 1.85081571768092561791175326276]
736 >>> iv.sec([0,2]) # Interval includes a singularity
737 [-inf, +inf]
738"""
740csc = r"""
741Computes the cosecant of `x`, `\mathrm{csc}(x) = \frac{1}{\sin(x)}`.
742This cosecant function is singular at `x = n \pi`, but with the
743exception of the point `x = 0`, ``csc(x)`` returns a finite result
744since `n \pi` cannot be represented exactly using floating-point
745arithmetic.
747 >>> from mpmath import *
748 >>> mp.dps = 25; mp.pretty = True
749 >>> csc(pi/3)
750 1.154700538379251529018298
751 >>> csc(10000001)
752 -1.864910497503629858938891
753 >>> csc(2+3j)
754 (0.09047320975320743980579048 + 0.04120098628857412646300981j)
755 >>> csc(inf)
756 nan
758Intervals are supported via :func:`mpmath.iv.csc`::
760 >>> iv.dps = 25; iv.pretty = True
761 >>> iv.csc([0,1]) # Interval includes a singularity
762 [1.18839510577812121626159943988, +inf]
763 >>> iv.csc([0,2])
764 [1.0, +inf]
765"""
767cot = r"""
768Computes the cotangent of `x`,
769`\mathrm{cot}(x) = \frac{1}{\tan(x)} = \frac{\cos(x)}{\sin(x)}`.
770This cotangent function is singular at `x = n \pi`, but with the
771exception of the point `x = 0`, ``cot(x)`` returns a finite result
772since `n \pi` cannot be represented exactly using floating-point
773arithmetic.
775 >>> from mpmath import *
776 >>> mp.dps = 25; mp.pretty = True
777 >>> cot(pi/3)
778 0.5773502691896257645091488
779 >>> cot(10000001)
780 1.574131876209625656003562
781 >>> cot(2+3j)
782 (-0.003739710376336956660117409 - 0.9967577965693583104609688j)
783 >>> cot(inf)
784 nan
786Intervals are supported via :func:`mpmath.iv.cot`::
788 >>> iv.dps = 25; iv.pretty = True
789 >>> iv.cot([0,1]) # Interval includes a singularity
790 [0.642092615934330703006419974862, +inf]
791 >>> iv.cot([1,2])
792 [-inf, +inf]
793"""
795acos = r"""
796Computes the inverse cosine or arccosine of `x`, `\cos^{-1}(x)`.
797Since `-1 \le \cos(x) \le 1` for real `x`, the inverse
798cosine is real-valued only for `-1 \le x \le 1`. On this interval,
799:func:`~mpmath.acos` is defined to be a monotonically decreasing
800function assuming values between `+\pi` and `0`.
802Basic values are::
804 >>> from mpmath import *
805 >>> mp.dps = 25; mp.pretty = True
806 >>> acos(-1)
807 3.141592653589793238462643
808 >>> acos(0)
809 1.570796326794896619231322
810 >>> acos(1)
811 0.0
812 >>> nprint(chop(taylor(acos, 0, 6)))
813 [1.5708, -1.0, 0.0, -0.166667, 0.0, -0.075, 0.0]
815:func:`~mpmath.acos` is defined so as to be a proper inverse function of
816`\cos(\theta)` for `0 \le \theta < \pi`.
817We have `\cos(\cos^{-1}(x)) = x` for all `x`, but
818`\cos^{-1}(\cos(x)) = x` only for `0 \le \Re[x] < \pi`::
820 >>> for x in [1, 10, -1, 2+3j, 10+3j]:
821 ... print("%s %s" % (cos(acos(x)), acos(cos(x))))
822 ...
823 1.0 1.0
824 (10.0 + 0.0j) 2.566370614359172953850574
825 -1.0 1.0
826 (2.0 + 3.0j) (2.0 + 3.0j)
827 (10.0 + 3.0j) (2.566370614359172953850574 - 3.0j)
829The inverse cosine has two branch points: `x = \pm 1`. :func:`~mpmath.acos`
830places the branch cuts along the line segments `(-\infty, -1)` and
831`(+1, +\infty)`. In general,
833.. math ::
835 \cos^{-1}(x) = \frac{\pi}{2} + i \log\left(ix + \sqrt{1-x^2} \right)
837where the principal-branch log and square root are implied.
838"""
840asin = r"""
841Computes the inverse sine or arcsine of `x`, `\sin^{-1}(x)`.
842Since `-1 \le \sin(x) \le 1` for real `x`, the inverse
843sine is real-valued only for `-1 \le x \le 1`.
844On this interval, it is defined to be a monotonically increasing
845function assuming values between `-\pi/2` and `\pi/2`.
847Basic values are::
849 >>> from mpmath import *
850 >>> mp.dps = 25; mp.pretty = True
851 >>> asin(-1)
852 -1.570796326794896619231322
853 >>> asin(0)
854 0.0
855 >>> asin(1)
856 1.570796326794896619231322
857 >>> nprint(chop(taylor(asin, 0, 6)))
858 [0.0, 1.0, 0.0, 0.166667, 0.0, 0.075, 0.0]
860:func:`~mpmath.asin` is defined so as to be a proper inverse function of
861`\sin(\theta)` for `-\pi/2 < \theta < \pi/2`.
862We have `\sin(\sin^{-1}(x)) = x` for all `x`, but
863`\sin^{-1}(\sin(x)) = x` only for `-\pi/2 < \Re[x] < \pi/2`::
865 >>> for x in [1, 10, -1, 1+3j, -2+3j]:
866 ... print("%s %s" % (chop(sin(asin(x))), asin(sin(x))))
867 ...
868 1.0 1.0
869 10.0 -0.5752220392306202846120698
870 -1.0 -1.0
871 (1.0 + 3.0j) (1.0 + 3.0j)
872 (-2.0 + 3.0j) (-1.141592653589793238462643 - 3.0j)
874The inverse sine has two branch points: `x = \pm 1`. :func:`~mpmath.asin`
875places the branch cuts along the line segments `(-\infty, -1)` and
876`(+1, +\infty)`. In general,
878.. math ::
880 \sin^{-1}(x) = -i \log\left(ix + \sqrt{1-x^2} \right)
882where the principal-branch log and square root are implied.
883"""
885atan = r"""
886Computes the inverse tangent or arctangent of `x`, `\tan^{-1}(x)`.
887This is a real-valued function for all real `x`, with range
888`(-\pi/2, \pi/2)`.
890Basic values are::
892 >>> from mpmath import *
893 >>> mp.dps = 25; mp.pretty = True
894 >>> atan(-inf)
895 -1.570796326794896619231322
896 >>> atan(-1)
897 -0.7853981633974483096156609
898 >>> atan(0)
899 0.0
900 >>> atan(1)
901 0.7853981633974483096156609
902 >>> atan(inf)
903 1.570796326794896619231322
904 >>> nprint(chop(taylor(atan, 0, 6)))
905 [0.0, 1.0, 0.0, -0.333333, 0.0, 0.2, 0.0]
907The inverse tangent is often used to compute angles. However,
908the atan2 function is often better for this as it preserves sign
909(see :func:`~mpmath.atan2`).
911:func:`~mpmath.atan` is defined so as to be a proper inverse function of
912`\tan(\theta)` for `-\pi/2 < \theta < \pi/2`.
913We have `\tan(\tan^{-1}(x)) = x` for all `x`, but
914`\tan^{-1}(\tan(x)) = x` only for `-\pi/2 < \Re[x] < \pi/2`::
916 >>> mp.dps = 25
917 >>> for x in [1, 10, -1, 1+3j, -2+3j]:
918 ... print("%s %s" % (tan(atan(x)), atan(tan(x))))
919 ...
920 1.0 1.0
921 10.0 0.5752220392306202846120698
922 -1.0 -1.0
923 (1.0 + 3.0j) (1.000000000000000000000001 + 3.0j)
924 (-2.0 + 3.0j) (1.141592653589793238462644 + 3.0j)
926The inverse tangent has two branch points: `x = \pm i`. :func:`~mpmath.atan`
927places the branch cuts along the line segments `(-i \infty, -i)` and
928`(+i, +i \infty)`. In general,
930.. math ::
932 \tan^{-1}(x) = \frac{i}{2}\left(\log(1-ix)-\log(1+ix)\right)
934where the principal-branch log is implied.
935"""
937acot = r"""Computes the inverse cotangent of `x`,
938`\mathrm{cot}^{-1}(x) = \tan^{-1}(1/x)`."""
940asec = r"""Computes the inverse secant of `x`,
941`\mathrm{sec}^{-1}(x) = \cos^{-1}(1/x)`."""
943acsc = r"""Computes the inverse cosecant of `x`,
944`\mathrm{csc}^{-1}(x) = \sin^{-1}(1/x)`."""
946coth = r"""Computes the hyperbolic cotangent of `x`,
947`\mathrm{coth}(x) = \frac{\cosh(x)}{\sinh(x)}`.
948"""
950sech = r"""Computes the hyperbolic secant of `x`,
951`\mathrm{sech}(x) = \frac{1}{\cosh(x)}`.
952"""
954csch = r"""Computes the hyperbolic cosecant of `x`,
955`\mathrm{csch}(x) = \frac{1}{\sinh(x)}`.
956"""
958acosh = r"""Computes the inverse hyperbolic cosine of `x`,
959`\mathrm{cosh}^{-1}(x) = \log(x+\sqrt{x+1}\sqrt{x-1})`.
960"""
962asinh = r"""Computes the inverse hyperbolic sine of `x`,
963`\mathrm{sinh}^{-1}(x) = \log(x+\sqrt{1+x^2})`.
964"""
966atanh = r"""Computes the inverse hyperbolic tangent of `x`,
967`\mathrm{tanh}^{-1}(x) = \frac{1}{2}\left(\log(1+x)-\log(1-x)\right)`.
968"""
970acoth = r"""Computes the inverse hyperbolic cotangent of `x`,
971`\mathrm{coth}^{-1}(x) = \tanh^{-1}(1/x)`."""
973asech = r"""Computes the inverse hyperbolic secant of `x`,
974`\mathrm{sech}^{-1}(x) = \cosh^{-1}(1/x)`."""
976acsch = r"""Computes the inverse hyperbolic cosecant of `x`,
977`\mathrm{csch}^{-1}(x) = \sinh^{-1}(1/x)`."""
981sinpi = r"""
982Computes `\sin(\pi x)`, more accurately than the expression
983``sin(pi*x)``::
985 >>> from mpmath import *
986 >>> mp.dps = 15; mp.pretty = True
987 >>> sinpi(10**10), sin(pi*(10**10))
988 (0.0, -2.23936276195592e-6)
989 >>> sinpi(10**10+0.5), sin(pi*(10**10+0.5))
990 (1.0, 0.999999999998721)
991"""
993cospi = r"""
994Computes `\cos(\pi x)`, more accurately than the expression
995``cos(pi*x)``::
997 >>> from mpmath import *
998 >>> mp.dps = 15; mp.pretty = True
999 >>> cospi(10**10), cos(pi*(10**10))
1000 (1.0, 0.999999999997493)
1001 >>> cospi(10**10+0.5), cos(pi*(10**10+0.5))
1002 (0.0, 1.59960492420134e-6)
1003"""
1005sinc = r"""
1006``sinc(x)`` computes the unnormalized sinc function, defined as
1008.. math ::
1010 \mathrm{sinc}(x) = \begin{cases}
1011 \sin(x)/x, & \mbox{if } x \ne 0 \\
1012 1, & \mbox{if } x = 0.
1013 \end{cases}
1015See :func:`~mpmath.sincpi` for the normalized sinc function.
1017Simple values and limits include::
1019 >>> from mpmath import *
1020 >>> mp.dps = 15; mp.pretty = True
1021 >>> sinc(0)
1022 1.0
1023 >>> sinc(1)
1024 0.841470984807897
1025 >>> sinc(inf)
1026 0.0
1028The integral of the sinc function is the sine integral Si::
1030 >>> quad(sinc, [0, 1])
1031 0.946083070367183
1032 >>> si(1)
1033 0.946083070367183
1034"""
1036sincpi = r"""
1037``sincpi(x)`` computes the normalized sinc function, defined as
1039.. math ::
1041 \mathrm{sinc}_{\pi}(x) = \begin{cases}
1042 \sin(\pi x)/(\pi x), & \mbox{if } x \ne 0 \\
1043 1, & \mbox{if } x = 0.
1044 \end{cases}
1046Equivalently, we have
1047`\mathrm{sinc}_{\pi}(x) = \mathrm{sinc}(\pi x)`.
1049The normalization entails that the function integrates
1050to unity over the entire real line::
1052 >>> from mpmath import *
1053 >>> mp.dps = 15; mp.pretty = True
1054 >>> quadosc(sincpi, [-inf, inf], period=2.0)
1055 1.0
1057Like, :func:`~mpmath.sinpi`, :func:`~mpmath.sincpi` is evaluated accurately
1058at its roots::
1060 >>> sincpi(10)
1061 0.0
1062"""
1064expj = r"""
1065Convenience function for computing `e^{ix}`::
1067 >>> from mpmath import *
1068 >>> mp.dps = 25; mp.pretty = True
1069 >>> expj(0)
1070 (1.0 + 0.0j)
1071 >>> expj(-1)
1072 (0.5403023058681397174009366 - 0.8414709848078965066525023j)
1073 >>> expj(j)
1074 (0.3678794411714423215955238 + 0.0j)
1075 >>> expj(1+j)
1076 (0.1987661103464129406288032 + 0.3095598756531121984439128j)
1077"""
1079expjpi = r"""
1080Convenience function for computing `e^{i \pi x}`.
1081Evaluation is accurate near zeros (see also :func:`~mpmath.cospi`,
1082:func:`~mpmath.sinpi`)::
1084 >>> from mpmath import *
1085 >>> mp.dps = 25; mp.pretty = True
1086 >>> expjpi(0)
1087 (1.0 + 0.0j)
1088 >>> expjpi(1)
1089 (-1.0 + 0.0j)
1090 >>> expjpi(0.5)
1091 (0.0 + 1.0j)
1092 >>> expjpi(-1)
1093 (-1.0 + 0.0j)
1094 >>> expjpi(j)
1095 (0.04321391826377224977441774 + 0.0j)
1096 >>> expjpi(1+j)
1097 (-0.04321391826377224977441774 + 0.0j)
1098"""
1100floor = r"""
1101Computes the floor of `x`, `\lfloor x \rfloor`, defined as
1102the largest integer less than or equal to `x`::
1104 >>> from mpmath import *
1105 >>> mp.pretty = False
1106 >>> floor(3.5)
1107 mpf('3.0')
1109.. note ::
1111 :func:`~mpmath.floor`, :func:`~mpmath.ceil` and :func:`~mpmath.nint` return a
1112 floating-point number, not a Python ``int``. If `\lfloor x \rfloor` is
1113 too large to be represented exactly at the present working precision,
1114 the result will be rounded, not necessarily in the direction
1115 implied by the mathematical definition of the function.
1117To avoid rounding, use *prec=0*::
1119 >>> mp.dps = 15
1120 >>> print(int(floor(10**30+1)))
1121 1000000000000000019884624838656
1122 >>> print(int(floor(10**30+1, prec=0)))
1123 1000000000000000000000000000001
1125The floor function is defined for complex numbers and
1126acts on the real and imaginary parts separately::
1128 >>> floor(3.25+4.75j)
1129 mpc(real='3.0', imag='4.0')
1130"""
1132ceil = r"""
1133Computes the ceiling of `x`, `\lceil x \rceil`, defined as
1134the smallest integer greater than or equal to `x`::
1136 >>> from mpmath import *
1137 >>> mp.pretty = False
1138 >>> ceil(3.5)
1139 mpf('4.0')
1141The ceiling function is defined for complex numbers and
1142acts on the real and imaginary parts separately::
1144 >>> ceil(3.25+4.75j)
1145 mpc(real='4.0', imag='5.0')
1147See notes about rounding for :func:`~mpmath.floor`.
1148"""
1150nint = r"""
1151Evaluates the nearest integer function, `\mathrm{nint}(x)`.
1152This gives the nearest integer to `x`; on a tie, it
1153gives the nearest even integer::
1155 >>> from mpmath import *
1156 >>> mp.pretty = False
1157 >>> nint(3.2)
1158 mpf('3.0')
1159 >>> nint(3.8)
1160 mpf('4.0')
1161 >>> nint(3.5)
1162 mpf('4.0')
1163 >>> nint(4.5)
1164 mpf('4.0')
1166The nearest integer function is defined for complex numbers and
1167acts on the real and imaginary parts separately::
1169 >>> nint(3.25+4.75j)
1170 mpc(real='3.0', imag='5.0')
1172See notes about rounding for :func:`~mpmath.floor`.
1173"""
1175frac = r"""
1176Gives the fractional part of `x`, defined as
1177`\mathrm{frac}(x) = x - \lfloor x \rfloor` (see :func:`~mpmath.floor`).
1178In effect, this computes `x` modulo 1, or `x+n` where
1179`n \in \mathbb{Z}` is such that `x+n \in [0,1)`::
1181 >>> from mpmath import *
1182 >>> mp.pretty = False
1183 >>> frac(1.25)
1184 mpf('0.25')
1185 >>> frac(3)
1186 mpf('0.0')
1187 >>> frac(-1.25)
1188 mpf('0.75')
1190For a complex number, the fractional part function applies to
1191the real and imaginary parts separately::
1193 >>> frac(2.25+3.75j)
1194 mpc(real='0.25', imag='0.75')
1196Plotted, the fractional part function gives a sawtooth
1197wave. The Fourier series coefficients have a simple
1198form::
1200 >>> mp.dps = 15
1201 >>> nprint(fourier(lambda x: frac(x)-0.5, [0,1], 4))
1202 ([0.0, 0.0, 0.0, 0.0, 0.0], [0.0, -0.31831, -0.159155, -0.106103, -0.0795775])
1203 >>> nprint([-1/(pi*k) for k in range(1,5)])
1204 [-0.31831, -0.159155, -0.106103, -0.0795775]
1206.. note::
1208 The fractional part is sometimes defined as a symmetric
1209 function, i.e. returning `-\mathrm{frac}(-x)` if `x < 0`.
1210 This convention is used, for instance, by Mathematica's
1211 ``FractionalPart``.
1213"""
1215sign = r"""
1216Returns the sign of `x`, defined as `\mathrm{sign}(x) = x / |x|`
1217(with the special case `\mathrm{sign}(0) = 0`)::
1219 >>> from mpmath import *
1220 >>> mp.dps = 15; mp.pretty = False
1221 >>> sign(10)
1222 mpf('1.0')
1223 >>> sign(-10)
1224 mpf('-1.0')
1225 >>> sign(0)
1226 mpf('0.0')
1228Note that the sign function is also defined for complex numbers,
1229for which it gives the projection onto the unit circle::
1231 >>> mp.dps = 15; mp.pretty = True
1232 >>> sign(1+j)
1233 (0.707106781186547 + 0.707106781186547j)
1235"""
1237arg = r"""
1238Computes the complex argument (phase) of `x`, defined as the
1239signed angle between the positive real axis and `x` in the
1240complex plane::
1242 >>> from mpmath import *
1243 >>> mp.dps = 15; mp.pretty = True
1244 >>> arg(3)
1245 0.0
1246 >>> arg(3+3j)
1247 0.785398163397448
1248 >>> arg(3j)
1249 1.5707963267949
1250 >>> arg(-3)
1251 3.14159265358979
1252 >>> arg(-3j)
1253 -1.5707963267949
1255The angle is defined to satisfy `-\pi < \arg(x) \le \pi` and
1256with the sign convention that a nonnegative imaginary part
1257results in a nonnegative argument.
1259The value returned by :func:`~mpmath.arg` is an ``mpf`` instance.
1260"""
1262fabs = r"""
1263Returns the absolute value of `x`, `|x|`. Unlike :func:`abs`,
1264:func:`~mpmath.fabs` converts non-mpmath numbers (such as ``int``)
1265into mpmath numbers::
1267 >>> from mpmath import *
1268 >>> mp.dps = 15; mp.pretty = False
1269 >>> fabs(3)
1270 mpf('3.0')
1271 >>> fabs(-3)
1272 mpf('3.0')
1273 >>> fabs(3+4j)
1274 mpf('5.0')
1275"""
1277re = r"""
1278Returns the real part of `x`, `\Re(x)`. :func:`~mpmath.re`
1279converts a non-mpmath number to an mpmath number::
1281 >>> from mpmath import *
1282 >>> mp.dps = 15; mp.pretty = False
1283 >>> re(3)
1284 mpf('3.0')
1285 >>> re(-1+4j)
1286 mpf('-1.0')
1287"""
1289im = r"""
1290Returns the imaginary part of `x`, `\Im(x)`. :func:`~mpmath.im`
1291converts a non-mpmath number to an mpmath number::
1293 >>> from mpmath import *
1294 >>> mp.dps = 15; mp.pretty = False
1295 >>> im(3)
1296 mpf('0.0')
1297 >>> im(-1+4j)
1298 mpf('4.0')
1299"""
1301conj = r"""
1302Returns the complex conjugate of `x`, `\overline{x}`. Unlike
1303``x.conjugate()``, :func:`~mpmath.im` converts `x` to a mpmath number::
1305 >>> from mpmath import *
1306 >>> mp.dps = 15; mp.pretty = False
1307 >>> conj(3)
1308 mpf('3.0')
1309 >>> conj(-1+4j)
1310 mpc(real='-1.0', imag='-4.0')
1311"""
1313polar = r"""
1314Returns the polar representation of the complex number `z`
1315as a pair `(r, \phi)` such that `z = r e^{i \phi}`::
1317 >>> from mpmath import *
1318 >>> mp.dps = 15; mp.pretty = True
1319 >>> polar(-2)
1320 (2.0, 3.14159265358979)
1321 >>> polar(3-4j)
1322 (5.0, -0.927295218001612)
1323"""
1325rect = r"""
1326Returns the complex number represented by polar
1327coordinates `(r, \phi)`::
1329 >>> from mpmath import *
1330 >>> mp.dps = 15; mp.pretty = True
1331 >>> chop(rect(2, pi))
1332 -2.0
1333 >>> rect(sqrt(2), -pi/4)
1334 (1.0 - 1.0j)
1335"""
1337expm1 = r"""
1338Computes `e^x - 1`, accurately for small `x`.
1340Unlike the expression ``exp(x) - 1``, ``expm1(x)`` does not suffer from
1341potentially catastrophic cancellation::
1343 >>> from mpmath import *
1344 >>> mp.dps = 15; mp.pretty = True
1345 >>> exp(1e-10)-1; print(expm1(1e-10))
1346 1.00000008274037e-10
1347 1.00000000005e-10
1348 >>> exp(1e-20)-1; print(expm1(1e-20))
1349 0.0
1350 1.0e-20
1351 >>> 1/(exp(1e-20)-1)
1352 Traceback (most recent call last):
1353 ...
1354 ZeroDivisionError
1355 >>> 1/expm1(1e-20)
1356 1.0e+20
1358Evaluation works for extremely tiny values::
1360 >>> expm1(0)
1361 0.0
1362 >>> expm1('1e-10000000')
1363 1.0e-10000000
1365"""
1367log1p = r"""
1368Computes `\log(1+x)`, accurately for small `x`.
1370 >>> from mpmath import *
1371 >>> mp.dps = 15; mp.pretty = True
1372 >>> log(1+1e-10); print(mp.log1p(1e-10))
1373 1.00000008269037e-10
1374 9.9999999995e-11
1375 >>> mp.log1p(1e-100j)
1376 (5.0e-201 + 1.0e-100j)
1377 >>> mp.log1p(0)
1378 0.0
1380"""
1383powm1 = r"""
1384Computes `x^y - 1`, accurately when `x^y` is very close to 1.
1386This avoids potentially catastrophic cancellation::
1388 >>> from mpmath import *
1389 >>> mp.dps = 15; mp.pretty = True
1390 >>> power(0.99999995, 1e-10) - 1
1391 0.0
1392 >>> powm1(0.99999995, 1e-10)
1393 -5.00000012791934e-18
1395Powers exactly equal to 1, and only those powers, yield 0 exactly::
1397 >>> powm1(-j, 4)
1398 (0.0 + 0.0j)
1399 >>> powm1(3, 0)
1400 0.0
1401 >>> powm1(fadd(-1, 1e-100, exact=True), 4)
1402 -4.0e-100
1404Evaluation works for extremely tiny `y`::
1406 >>> powm1(2, '1e-100000')
1407 6.93147180559945e-100001
1408 >>> powm1(j, '1e-1000')
1409 (-1.23370055013617e-2000 + 1.5707963267949e-1000j)
1411"""
1413root = r"""
1414``root(z, n, k=0)`` computes an `n`-th root of `z`, i.e. returns a number
1415`r` that (up to possible approximation error) satisfies `r^n = z`.
1416(``nthroot`` is available as an alias for ``root``.)
1418Every complex number `z \ne 0` has `n` distinct `n`-th roots, which are
1419equidistant points on a circle with radius `|z|^{1/n}`, centered around the
1420origin. A specific root may be selected using the optional index
1421`k`. The roots are indexed counterclockwise, starting with `k = 0` for the root
1422closest to the positive real half-axis.
1424The `k = 0` root is the so-called principal `n`-th root, often denoted by
1425`\sqrt[n]{z}` or `z^{1/n}`, and also given by `\exp(\log(z) / n)`. If `z` is
1426a positive real number, the principal root is just the unique positive
1427`n`-th root of `z`. Under some circumstances, non-principal real roots exist:
1428for positive real `z`, `n` even, there is a negative root given by `k = n/2`;
1429for negative real `z`, `n` odd, there is a negative root given by `k = (n-1)/2`.
1431To obtain all roots with a simple expression, use
1432``[root(z,n,k) for k in range(n)]``.
1434An important special case, ``root(1, n, k)`` returns the `k`-th `n`-th root of
1435unity, `\zeta_k = e^{2 \pi i k / n}`. Alternatively, :func:`~mpmath.unitroots`
1436provides a slightly more convenient way to obtain the roots of unity,
1437including the option to compute only the primitive roots of unity.
1439Both `k` and `n` should be integers; `k` outside of ``range(n)`` will be
1440reduced modulo `n`. If `n` is negative, `x^{-1/n} = 1/x^{1/n}` (or
1441the equivalent reciprocal for a non-principal root with `k \ne 0`) is computed.
1443:func:`~mpmath.root` is implemented to use Newton's method for small
1444`n`. At high precision, this makes `x^{1/n}` not much more
1445expensive than the regular exponentiation, `x^n`. For very large
1446`n`, :func:`~mpmath.nthroot` falls back to use the exponential function.
1448**Examples**
1450:func:`~mpmath.nthroot`/:func:`~mpmath.root` is faster and more accurate than raising to a
1451floating-point fraction::
1453 >>> from mpmath import *
1454 >>> mp.dps = 15; mp.pretty = False
1455 >>> 16807 ** (mpf(1)/5)
1456 mpf('7.0000000000000009')
1457 >>> root(16807, 5)
1458 mpf('7.0')
1459 >>> nthroot(16807, 5) # Alias
1460 mpf('7.0')
1462A high-precision root::
1464 >>> mp.dps = 50; mp.pretty = True
1465 >>> nthroot(10, 5)
1466 1.584893192461113485202101373391507013269442133825
1467 >>> nthroot(10, 5) ** 5
1468 10.0
1470Computing principal and non-principal square and cube roots::
1472 >>> mp.dps = 15
1473 >>> root(10, 2)
1474 3.16227766016838
1475 >>> root(10, 2, 1)
1476 -3.16227766016838
1477 >>> root(-10, 3)
1478 (1.07721734501594 + 1.86579517236206j)
1479 >>> root(-10, 3, 1)
1480 -2.15443469003188
1481 >>> root(-10, 3, 2)
1482 (1.07721734501594 - 1.86579517236206j)
1484All the 7th roots of a complex number::
1486 >>> for r in [root(3+4j, 7, k) for k in range(7)]:
1487 ... print("%s %s" % (r, r**7))
1488 ...
1489 (1.24747270589553 + 0.166227124177353j) (3.0 + 4.0j)
1490 (0.647824911301003 + 1.07895435170559j) (3.0 + 4.0j)
1491 (-0.439648254723098 + 1.17920694574172j) (3.0 + 4.0j)
1492 (-1.19605731775069 + 0.391492658196305j) (3.0 + 4.0j)
1493 (-1.05181082538903 - 0.691023585965793j) (3.0 + 4.0j)
1494 (-0.115529328478668 - 1.25318497558335j) (3.0 + 4.0j)
1495 (0.907748109144957 - 0.871672518271819j) (3.0 + 4.0j)
1497Cube roots of unity::
1499 >>> for k in range(3): print(root(1, 3, k))
1500 ...
1501 1.0
1502 (-0.5 + 0.866025403784439j)
1503 (-0.5 - 0.866025403784439j)
1505Some exact high order roots::
1507 >>> root(75**210, 105)
1508 5625.0
1509 >>> root(1, 128, 96)
1510 (0.0 - 1.0j)
1511 >>> root(4**128, 128, 96)
1512 (0.0 - 4.0j)
1514"""
1516unitroots = r"""
1517``unitroots(n)`` returns `\zeta_0, \zeta_1, \ldots, \zeta_{n-1}`,
1518all the distinct `n`-th roots of unity, as a list. If the option
1519*primitive=True* is passed, only the primitive roots are returned.
1521Every `n`-th root of unity satisfies `(\zeta_k)^n = 1`. There are `n` distinct
1522roots for each `n` (`\zeta_k` and `\zeta_j` are the same when
1523`k = j \pmod n`), which form a regular polygon with vertices on the unit
1524circle. They are ordered counterclockwise with increasing `k`, starting
1525with `\zeta_0 = 1`.
1527**Examples**
1529The roots of unity up to `n = 4`::
1531 >>> from mpmath import *
1532 >>> mp.dps = 15; mp.pretty = True
1533 >>> nprint(unitroots(1))
1534 [1.0]
1535 >>> nprint(unitroots(2))
1536 [1.0, -1.0]
1537 >>> nprint(unitroots(3))
1538 [1.0, (-0.5 + 0.866025j), (-0.5 - 0.866025j)]
1539 >>> nprint(unitroots(4))
1540 [1.0, (0.0 + 1.0j), -1.0, (0.0 - 1.0j)]
1542Roots of unity form a geometric series that sums to 0::
1544 >>> mp.dps = 50
1545 >>> chop(fsum(unitroots(25)))
1546 0.0
1548Primitive roots up to `n = 4`::
1550 >>> mp.dps = 15
1551 >>> nprint(unitroots(1, primitive=True))
1552 [1.0]
1553 >>> nprint(unitroots(2, primitive=True))
1554 [-1.0]
1555 >>> nprint(unitroots(3, primitive=True))
1556 [(-0.5 + 0.866025j), (-0.5 - 0.866025j)]
1557 >>> nprint(unitroots(4, primitive=True))
1558 [(0.0 + 1.0j), (0.0 - 1.0j)]
1560There are only four primitive 12th roots::
1562 >>> nprint(unitroots(12, primitive=True))
1563 [(0.866025 + 0.5j), (-0.866025 + 0.5j), (-0.866025 - 0.5j), (0.866025 - 0.5j)]
1565The `n`-th roots of unity form a group, the cyclic group of order `n`.
1566Any primitive root `r` is a generator for this group, meaning that
1567`r^0, r^1, \ldots, r^{n-1}` gives the whole set of unit roots (in
1568some permuted order)::
1570 >>> for r in unitroots(6): print(r)
1571 ...
1572 1.0
1573 (0.5 + 0.866025403784439j)
1574 (-0.5 + 0.866025403784439j)
1575 -1.0
1576 (-0.5 - 0.866025403784439j)
1577 (0.5 - 0.866025403784439j)
1578 >>> r = unitroots(6, primitive=True)[1]
1579 >>> for k in range(6): print(chop(r**k))
1580 ...
1581 1.0
1582 (0.5 - 0.866025403784439j)
1583 (-0.5 - 0.866025403784439j)
1584 -1.0
1585 (-0.5 + 0.866025403784438j)
1586 (0.5 + 0.866025403784438j)
1588The number of primitive roots equals the Euler totient function `\phi(n)`::
1590 >>> [len(unitroots(n, primitive=True)) for n in range(1,20)]
1591 [1, 1, 2, 2, 4, 2, 6, 4, 6, 4, 10, 4, 12, 6, 8, 8, 16, 6, 18]
1593"""
1596log = r"""
1597Computes the base-`b` logarithm of `x`, `\log_b(x)`. If `b` is
1598unspecified, :func:`~mpmath.log` computes the natural (base `e`) logarithm
1599and is equivalent to :func:`~mpmath.ln`. In general, the base `b` logarithm
1600is defined in terms of the natural logarithm as
1601`\log_b(x) = \ln(x)/\ln(b)`.
1603By convention, we take `\log(0) = -\infty`.
1605The natural logarithm is real if `x > 0` and complex if `x < 0` or if
1606`x` is complex. The principal branch of the complex logarithm is
1607used, meaning that `\Im(\ln(x)) = -\pi < \arg(x) \le \pi`.
1609**Examples**
1611Some basic values and limits::
1613 >>> from mpmath import *
1614 >>> mp.dps = 15; mp.pretty = True
1615 >>> log(1)
1616 0.0
1617 >>> log(2)
1618 0.693147180559945
1619 >>> log(1000,10)
1620 3.0
1621 >>> log(4, 16)
1622 0.5
1623 >>> log(j)
1624 (0.0 + 1.5707963267949j)
1625 >>> log(-1)
1626 (0.0 + 3.14159265358979j)
1627 >>> log(0)
1628 -inf
1629 >>> log(inf)
1630 +inf
1632The natural logarithm is the antiderivative of `1/x`::
1634 >>> quad(lambda x: 1/x, [1, 5])
1635 1.6094379124341
1636 >>> log(5)
1637 1.6094379124341
1638 >>> diff(log, 10)
1639 0.1
1641The Taylor series expansion of the natural logarithm around
1642`x = 1` has coefficients `(-1)^{n+1}/n`::
1644 >>> nprint(taylor(log, 1, 7))
1645 [0.0, 1.0, -0.5, 0.333333, -0.25, 0.2, -0.166667, 0.142857]
1647:func:`~mpmath.log` supports arbitrary precision evaluation::
1649 >>> mp.dps = 50
1650 >>> log(pi)
1651 1.1447298858494001741434273513530587116472948129153
1652 >>> log(pi, pi**3)
1653 0.33333333333333333333333333333333333333333333333333
1654 >>> mp.dps = 25
1655 >>> log(3+4j)
1656 (1.609437912434100374600759 + 0.9272952180016122324285125j)
1657"""
1659log10 = r"""
1660Computes the base-10 logarithm of `x`, `\log_{10}(x)`. ``log10(x)``
1661is equivalent to ``log(x, 10)``.
1662"""
1664fmod = r"""
1665Converts `x` and `y` to mpmath numbers and returns `x \mod y`.
1666For mpmath numbers, this is equivalent to ``x % y``.
1668 >>> from mpmath import *
1669 >>> mp.dps = 15; mp.pretty = True
1670 >>> fmod(100, pi)
1671 2.61062773871641
1673You can use :func:`~mpmath.fmod` to compute fractional parts of numbers::
1675 >>> fmod(10.25, 1)
1676 0.25
1678"""
1680radians = r"""
1681Converts the degree angle `x` to radians::
1683 >>> from mpmath import *
1684 >>> mp.dps = 15; mp.pretty = True
1685 >>> radians(60)
1686 1.0471975511966
1687"""
1689degrees = r"""
1690Converts the radian angle `x` to a degree angle::
1692 >>> from mpmath import *
1693 >>> mp.dps = 15; mp.pretty = True
1694 >>> degrees(pi/3)
1695 60.0
1696"""
1698atan2 = r"""
1699Computes the two-argument arctangent, `\mathrm{atan2}(y, x)`,
1700giving the signed angle between the positive `x`-axis and the
1701point `(x, y)` in the 2D plane. This function is defined for
1702real `x` and `y` only.
1704The two-argument arctangent essentially computes
1705`\mathrm{atan}(y/x)`, but accounts for the signs of both
1706`x` and `y` to give the angle for the correct quadrant. The
1707following examples illustrate the difference::
1709 >>> from mpmath import *
1710 >>> mp.dps = 15; mp.pretty = True
1711 >>> atan2(1,1), atan(1/1.)
1712 (0.785398163397448, 0.785398163397448)
1713 >>> atan2(1,-1), atan(1/-1.)
1714 (2.35619449019234, -0.785398163397448)
1715 >>> atan2(-1,1), atan(-1/1.)
1716 (-0.785398163397448, -0.785398163397448)
1717 >>> atan2(-1,-1), atan(-1/-1.)
1718 (-2.35619449019234, 0.785398163397448)
1720The angle convention is the same as that used for the complex
1721argument; see :func:`~mpmath.arg`.
1722"""
1724fibonacci = r"""
1725``fibonacci(n)`` computes the `n`-th Fibonacci number, `F(n)`. The
1726Fibonacci numbers are defined by the recurrence `F(n) = F(n-1) + F(n-2)`
1727with the initial values `F(0) = 0`, `F(1) = 1`. :func:`~mpmath.fibonacci`
1728extends this definition to arbitrary real and complex arguments
1729using the formula
1731.. math ::
1733 F(z) = \frac{\phi^z - \cos(\pi z) \phi^{-z}}{\sqrt 5}
1735where `\phi` is the golden ratio. :func:`~mpmath.fibonacci` also uses this
1736continuous formula to compute `F(n)` for extremely large `n`, where
1737calculating the exact integer would be wasteful.
1739For convenience, :func:`~mpmath.fib` is available as an alias for
1740:func:`~mpmath.fibonacci`.
1742**Basic examples**
1744Some small Fibonacci numbers are::
1746 >>> from mpmath import *
1747 >>> mp.dps = 15; mp.pretty = True
1748 >>> for i in range(10):
1749 ... print(fibonacci(i))
1750 ...
1751 0.0
1752 1.0
1753 1.0
1754 2.0
1755 3.0
1756 5.0
1757 8.0
1758 13.0
1759 21.0
1760 34.0
1761 >>> fibonacci(50)
1762 12586269025.0
1764The recurrence for `F(n)` extends backwards to negative `n`::
1766 >>> for i in range(10):
1767 ... print(fibonacci(-i))
1768 ...
1769 0.0
1770 1.0
1771 -1.0
1772 2.0
1773 -3.0
1774 5.0
1775 -8.0
1776 13.0
1777 -21.0
1778 34.0
1780Large Fibonacci numbers will be computed approximately unless
1781the precision is set high enough::
1783 >>> fib(200)
1784 2.8057117299251e+41
1785 >>> mp.dps = 45
1786 >>> fib(200)
1787 280571172992510140037611932413038677189525.0
1789:func:`~mpmath.fibonacci` can compute approximate Fibonacci numbers
1790of stupendous size::
1792 >>> mp.dps = 15
1793 >>> fibonacci(10**25)
1794 3.49052338550226e+2089876402499787337692720
1796**Real and complex arguments**
1798The extended Fibonacci function is an analytic function. The
1799property `F(z) = F(z-1) + F(z-2)` holds for arbitrary `z`::
1801 >>> mp.dps = 15
1802 >>> fib(pi)
1803 2.1170270579161
1804 >>> fib(pi-1) + fib(pi-2)
1805 2.1170270579161
1806 >>> fib(3+4j)
1807 (-5248.51130728372 - 14195.962288353j)
1808 >>> fib(2+4j) + fib(1+4j)
1809 (-5248.51130728372 - 14195.962288353j)
1811The Fibonacci function has infinitely many roots on the
1812negative half-real axis. The first root is at 0, the second is
1813close to -0.18, and then there are infinitely many roots that
1814asymptotically approach `-n+1/2`::
1816 >>> findroot(fib, -0.2)
1817 -0.183802359692956
1818 >>> findroot(fib, -2)
1819 -1.57077646820395
1820 >>> findroot(fib, -17)
1821 -16.4999999596115
1822 >>> findroot(fib, -24)
1823 -23.5000000000479
1825**Mathematical relationships**
1827For large `n`, `F(n+1)/F(n)` approaches the golden ratio::
1829 >>> mp.dps = 50
1830 >>> fibonacci(101)/fibonacci(100)
1831 1.6180339887498948482045868343656381177203127439638
1832 >>> +phi
1833 1.6180339887498948482045868343656381177203091798058
1835The sum of reciprocal Fibonacci numbers converges to an irrational
1836number for which no closed form expression is known::
1838 >>> mp.dps = 15
1839 >>> nsum(lambda n: 1/fib(n), [1, inf])
1840 3.35988566624318
1842Amazingly, however, the sum of odd-index reciprocal Fibonacci
1843numbers can be expressed in terms of a Jacobi theta function::
1845 >>> nsum(lambda n: 1/fib(2*n+1), [0, inf])
1846 1.82451515740692
1847 >>> sqrt(5)*jtheta(2,0,(3-sqrt(5))/2)**2/4
1848 1.82451515740692
1850Some related sums can be done in closed form::
1852 >>> nsum(lambda k: 1/(1+fib(2*k+1)), [0, inf])
1853 1.11803398874989
1854 >>> phi - 0.5
1855 1.11803398874989
1856 >>> f = lambda k:(-1)**(k+1) / sum(fib(n)**2 for n in range(1,int(k+1)))
1857 >>> nsum(f, [1, inf])
1858 0.618033988749895
1859 >>> phi-1
1860 0.618033988749895
1862**References**
18641. http://mathworld.wolfram.com/FibonacciNumber.html
1865"""
1867altzeta = r"""
1868Gives the Dirichlet eta function, `\eta(s)`, also known as the
1869alternating zeta function. This function is defined in analogy
1870with the Riemann zeta function as providing the sum of the
1871alternating series
1873.. math ::
1875 \eta(s) = \sum_{k=0}^{\infty} \frac{(-1)^k}{k^s}
1876 = 1-\frac{1}{2^s}+\frac{1}{3^s}-\frac{1}{4^s}+\ldots
1878The eta function, unlike the Riemann zeta function, is an entire
1879function, having a finite value for all complex `s`. The special case
1880`\eta(1) = \log(2)` gives the value of the alternating harmonic series.
1882The alternating zeta function may expressed using the Riemann zeta function
1883as `\eta(s) = (1 - 2^{1-s}) \zeta(s)`. It can also be expressed
1884in terms of the Hurwitz zeta function, for example using
1885:func:`~mpmath.dirichlet` (see documentation for that function).
1887**Examples**
1889Some special values are::
1891 >>> from mpmath import *
1892 >>> mp.dps = 15; mp.pretty = True
1893 >>> altzeta(1)
1894 0.693147180559945
1895 >>> altzeta(0)
1896 0.5
1897 >>> altzeta(-1)
1898 0.25
1899 >>> altzeta(-2)
1900 0.0
1902An example of a sum that can be computed more accurately and
1903efficiently via :func:`~mpmath.altzeta` than via numerical summation::
1905 >>> sum(-(-1)**n / mpf(n)**2.5 for n in range(1, 100))
1906 0.867204951503984
1907 >>> altzeta(2.5)
1908 0.867199889012184
1910At positive even integers, the Dirichlet eta function
1911evaluates to a rational multiple of a power of `\pi`::
1913 >>> altzeta(2)
1914 0.822467033424113
1915 >>> pi**2/12
1916 0.822467033424113
1918Like the Riemann zeta function, `\eta(s)`, approaches 1
1919as `s` approaches positive infinity, although it does
1920so from below rather than from above::
1922 >>> altzeta(30)
1923 0.999999999068682
1924 >>> altzeta(inf)
1925 1.0
1926 >>> mp.pretty = False
1927 >>> altzeta(1000, rounding='d')
1928 mpf('0.99999999999999989')
1929 >>> altzeta(1000, rounding='u')
1930 mpf('1.0')
1932**References**
19341. http://mathworld.wolfram.com/DirichletEtaFunction.html
19362. http://en.wikipedia.org/wiki/Dirichlet_eta_function
1937"""
1939factorial = r"""
1940Computes the factorial, `x!`. For integers `n \ge 0`, we have
1941`n! = 1 \cdot 2 \cdots (n-1) \cdot n` and more generally the factorial
1942is defined for real or complex `x` by `x! = \Gamma(x+1)`.
1944**Examples**
1946Basic values and limits::
1948 >>> from mpmath import *
1949 >>> mp.dps = 15; mp.pretty = True
1950 >>> for k in range(6):
1951 ... print("%s %s" % (k, fac(k)))
1952 ...
1953 0 1.0
1954 1 1.0
1955 2 2.0
1956 3 6.0
1957 4 24.0
1958 5 120.0
1959 >>> fac(inf)
1960 +inf
1961 >>> fac(0.5), sqrt(pi)/2
1962 (0.886226925452758, 0.886226925452758)
1964For large positive `x`, `x!` can be approximated by
1965Stirling's formula::
1967 >>> x = 10**10
1968 >>> fac(x)
1969 2.32579620567308e+95657055186
1970 >>> sqrt(2*pi*x)*(x/e)**x
1971 2.32579597597705e+95657055186
1973:func:`~mpmath.fac` supports evaluation for astronomically large values::
1975 >>> fac(10**30)
1976 6.22311232304258e+29565705518096748172348871081098
1978Reciprocal factorials appear in the Taylor series of the
1979exponential function (among many other contexts)::
1981 >>> nsum(lambda k: 1/fac(k), [0, inf]), exp(1)
1982 (2.71828182845905, 2.71828182845905)
1983 >>> nsum(lambda k: pi**k/fac(k), [0, inf]), exp(pi)
1984 (23.1406926327793, 23.1406926327793)
1986"""
1988gamma = r"""
1989Computes the gamma function, `\Gamma(x)`. The gamma function is a
1990shifted version of the ordinary factorial, satisfying
1991`\Gamma(n) = (n-1)!` for integers `n > 0`. More generally, it
1992is defined by
1994.. math ::
1996 \Gamma(x) = \int_0^{\infty} t^{x-1} e^{-t}\, dt
1998for any real or complex `x` with `\Re(x) > 0` and for `\Re(x) < 0`
1999by analytic continuation.
2001**Examples**
2003Basic values and limits::
2005 >>> from mpmath import *
2006 >>> mp.dps = 15; mp.pretty = True
2007 >>> for k in range(1, 6):
2008 ... print("%s %s" % (k, gamma(k)))
2009 ...
2010 1 1.0
2011 2 1.0
2012 3 2.0
2013 4 6.0
2014 5 24.0
2015 >>> gamma(inf)
2016 +inf
2017 >>> gamma(0)
2018 Traceback (most recent call last):
2019 ...
2020 ValueError: gamma function pole
2022The gamma function of a half-integer is a rational multiple of
2023`\sqrt{\pi}`::
2025 >>> gamma(0.5), sqrt(pi)
2026 (1.77245385090552, 1.77245385090552)
2027 >>> gamma(1.5), sqrt(pi)/2
2028 (0.886226925452758, 0.886226925452758)
2030We can check the integral definition::
2032 >>> gamma(3.5)
2033 3.32335097044784
2034 >>> quad(lambda t: t**2.5*exp(-t), [0,inf])
2035 3.32335097044784
2037:func:`~mpmath.gamma` supports arbitrary-precision evaluation and
2038complex arguments::
2040 >>> mp.dps = 50
2041 >>> gamma(sqrt(3))
2042 0.91510229697308632046045539308226554038315280564184
2043 >>> mp.dps = 25
2044 >>> gamma(2j)
2045 (0.009902440080927490985955066 - 0.07595200133501806872408048j)
2047Arguments can also be large. Note that the gamma function grows
2048very quickly::
2050 >>> mp.dps = 15
2051 >>> gamma(10**20)
2052 1.9328495143101e+1956570551809674817225
2054"""
2056psi = r"""
2057Gives the polygamma function of order `m` of `z`, `\psi^{(m)}(z)`.
2058Special cases are known as the *digamma function* (`\psi^{(0)}(z)`),
2059the *trigamma function* (`\psi^{(1)}(z)`), etc. The polygamma
2060functions are defined as the logarithmic derivatives of the gamma
2061function:
2063.. math ::
2065 \psi^{(m)}(z) = \left(\frac{d}{dz}\right)^{m+1} \log \Gamma(z)
2067In particular, `\psi^{(0)}(z) = \Gamma'(z)/\Gamma(z)`. In the
2068present implementation of :func:`~mpmath.psi`, the order `m` must be a
2069nonnegative integer, while the argument `z` may be an arbitrary
2070complex number (with exception for the polygamma function's poles
2071at `z = 0, -1, -2, \ldots`).
2073**Examples**
2075For various rational arguments, the polygamma function reduces to
2076a combination of standard mathematical constants::
2078 >>> from mpmath import *
2079 >>> mp.dps = 25; mp.pretty = True
2080 >>> psi(0, 1), -euler
2081 (-0.5772156649015328606065121, -0.5772156649015328606065121)
2082 >>> psi(1, '1/4'), pi**2+8*catalan
2083 (17.19732915450711073927132, 17.19732915450711073927132)
2084 >>> psi(2, '1/2'), -14*apery
2085 (-16.82879664423431999559633, -16.82879664423431999559633)
2087The polygamma functions are derivatives of each other::
2089 >>> diff(lambda x: psi(3, x), pi), psi(4, pi)
2090 (-0.1105749312578862734526952, -0.1105749312578862734526952)
2091 >>> quad(lambda x: psi(4, x), [2, 3]), psi(3,3)-psi(3,2)
2092 (-0.375, -0.375)
2094The digamma function diverges logarithmically as `z \to \infty`,
2095while higher orders tend to zero::
2097 >>> psi(0,inf), psi(1,inf), psi(2,inf)
2098 (+inf, 0.0, 0.0)
2100Evaluation for a complex argument::
2102 >>> psi(2, -1-2j)
2103 (0.03902435405364952654838445 + 0.1574325240413029954685366j)
2105Evaluation is supported for large orders `m` and/or large
2106arguments `z`::
2108 >>> psi(3, 10**100)
2109 2.0e-300
2110 >>> psi(250, 10**30+10**20*j)
2111 (-1.293142504363642687204865e-7010 + 3.232856260909107391513108e-7018j)
2113**Application to infinite series**
2115Any infinite series where the summand is a rational function of
2116the index `k` can be evaluated in closed form in terms of polygamma
2117functions of the roots and poles of the summand::
2119 >>> a = sqrt(2)
2120 >>> b = sqrt(3)
2121 >>> nsum(lambda k: 1/((k+a)**2*(k+b)), [0, inf])
2122 0.4049668927517857061917531
2123 >>> (psi(0,a)-psi(0,b)-a*psi(1,a)+b*psi(1,a))/(a-b)**2
2124 0.4049668927517857061917531
2126This follows from the series representation (`m > 0`)
2128.. math ::
2130 \psi^{(m)}(z) = (-1)^{m+1} m! \sum_{k=0}^{\infty}
2131 \frac{1}{(z+k)^{m+1}}.
2133Since the roots of a polynomial may be complex, it is sometimes
2134necessary to use the complex polygamma function to evaluate
2135an entirely real-valued sum::
2137 >>> nsum(lambda k: 1/(k**2-2*k+3), [0, inf])
2138 1.694361433907061256154665
2139 >>> nprint(polyroots([1,-2,3]))
2140 [(1.0 - 1.41421j), (1.0 + 1.41421j)]
2141 >>> r1 = 1-sqrt(2)*j
2142 >>> r2 = r1.conjugate()
2143 >>> (psi(0,-r2)-psi(0,-r1))/(r1-r2)
2144 (1.694361433907061256154665 + 0.0j)
2146"""
2148digamma = r"""
2149Shortcut for ``psi(0,z)``.
2150"""
2152harmonic = r"""
2153If `n` is an integer, ``harmonic(n)`` gives a floating-point
2154approximation of the `n`-th harmonic number `H(n)`, defined as
2156.. math ::
2158 H(n) = 1 + \frac{1}{2} + \frac{1}{3} + \ldots + \frac{1}{n}
2160The first few harmonic numbers are::
2162 >>> from mpmath import *
2163 >>> mp.dps = 15; mp.pretty = True
2164 >>> for n in range(8):
2165 ... print("%s %s" % (n, harmonic(n)))
2166 ...
2167 0 0.0
2168 1 1.0
2169 2 1.5
2170 3 1.83333333333333
2171 4 2.08333333333333
2172 5 2.28333333333333
2173 6 2.45
2174 7 2.59285714285714
2176The infinite harmonic series `1 + 1/2 + 1/3 + \ldots` diverges::
2178 >>> harmonic(inf)
2179 +inf
2181:func:`~mpmath.harmonic` is evaluated using the digamma function rather
2182than by summing the harmonic series term by term. It can therefore
2183be computed quickly for arbitrarily large `n`, and even for
2184nonintegral arguments::
2186 >>> harmonic(10**100)
2187 230.835724964306
2188 >>> harmonic(0.5)
2189 0.613705638880109
2190 >>> harmonic(3+4j)
2191 (2.24757548223494 + 0.850502209186044j)
2193:func:`~mpmath.harmonic` supports arbitrary precision evaluation::
2195 >>> mp.dps = 50
2196 >>> harmonic(11)
2197 3.0198773448773448773448773448773448773448773448773
2198 >>> harmonic(pi)
2199 1.8727388590273302654363491032336134987519132374152
2201The harmonic series diverges, but at a glacial pace. It is possible
2202to calculate the exact number of terms required before the sum
2203exceeds a given amount, say 100::
2205 >>> mp.dps = 50
2206 >>> v = 10**findroot(lambda x: harmonic(10**x) - 100, 10)
2207 >>> v
2208 15092688622113788323693563264538101449859496.864101
2209 >>> v = int(ceil(v))
2210 >>> print(v)
2211 15092688622113788323693563264538101449859497
2212 >>> harmonic(v-1)
2213 99.999999999999999999999999999999999999999999942747
2214 >>> harmonic(v)
2215 100.000000000000000000000000000000000000000000009
2217"""
2219bernoulli = r"""
2220Computes the nth Bernoulli number, `B_n`, for any integer `n \ge 0`.
2222The Bernoulli numbers are rational numbers, but this function
2223returns a floating-point approximation. To obtain an exact
2224fraction, use :func:`~mpmath.bernfrac` instead.
2226**Examples**
2228Numerical values of the first few Bernoulli numbers::
2230 >>> from mpmath import *
2231 >>> mp.dps = 15; mp.pretty = True
2232 >>> for n in range(15):
2233 ... print("%s %s" % (n, bernoulli(n)))
2234 ...
2235 0 1.0
2236 1 -0.5
2237 2 0.166666666666667
2238 3 0.0
2239 4 -0.0333333333333333
2240 5 0.0
2241 6 0.0238095238095238
2242 7 0.0
2243 8 -0.0333333333333333
2244 9 0.0
2245 10 0.0757575757575758
2246 11 0.0
2247 12 -0.253113553113553
2248 13 0.0
2249 14 1.16666666666667
2251Bernoulli numbers can be approximated with arbitrary precision::
2253 >>> mp.dps = 50
2254 >>> bernoulli(100)
2255 -2.8382249570693706959264156336481764738284680928013e+78
2257Arbitrarily large `n` are supported::
2259 >>> mp.dps = 15
2260 >>> bernoulli(10**20 + 2)
2261 3.09136296657021e+1876752564973863312327
2263The Bernoulli numbers are related to the Riemann zeta function
2264at integer arguments::
2266 >>> -bernoulli(8) * (2*pi)**8 / (2*fac(8))
2267 1.00407735619794
2268 >>> zeta(8)
2269 1.00407735619794
2271**Algorithm**
2273For small `n` (`n < 3000`) :func:`~mpmath.bernoulli` uses a recurrence
2274formula due to Ramanujan. All results in this range are cached,
2275so sequential computation of small Bernoulli numbers is
2276guaranteed to be fast.
2278For larger `n`, `B_n` is evaluated in terms of the Riemann zeta
2279function.
2280"""
2282stieltjes = r"""
2283For a nonnegative integer `n`, ``stieltjes(n)`` computes the
2284`n`-th Stieltjes constant `\gamma_n`, defined as the
2285`n`-th coefficient in the Laurent series expansion of the
2286Riemann zeta function around the pole at `s = 1`. That is,
2287we have:
2289.. math ::
2291 \zeta(s) = \frac{1}{s-1} \sum_{n=0}^{\infty}
2292 \frac{(-1)^n}{n!} \gamma_n (s-1)^n
2294More generally, ``stieltjes(n, a)`` gives the corresponding
2295coefficient `\gamma_n(a)` for the Hurwitz zeta function
2296`\zeta(s,a)` (with `\gamma_n = \gamma_n(1)`).
2298**Examples**
2300The zeroth Stieltjes constant is just Euler's constant `\gamma`::
2302 >>> from mpmath import *
2303 >>> mp.dps = 15; mp.pretty = True
2304 >>> stieltjes(0)
2305 0.577215664901533
2307Some more values are::
2309 >>> stieltjes(1)
2310 -0.0728158454836767
2311 >>> stieltjes(10)
2312 0.000205332814909065
2313 >>> stieltjes(30)
2314 0.00355772885557316
2315 >>> stieltjes(1000)
2316 -1.57095384420474e+486
2317 >>> stieltjes(2000)
2318 2.680424678918e+1109
2319 >>> stieltjes(1, 2.5)
2320 -0.23747539175716
2322An alternative way to compute `\gamma_1`::
2324 >>> diff(extradps(15)(lambda x: 1/(x-1) - zeta(x)), 1)
2325 -0.0728158454836767
2327:func:`~mpmath.stieltjes` supports arbitrary precision evaluation::
2329 >>> mp.dps = 50
2330 >>> stieltjes(2)
2331 -0.0096903631928723184845303860352125293590658061013408
2333**Algorithm**
2335:func:`~mpmath.stieltjes` numerically evaluates the integral in
2336the following representation due to Ainsworth, Howell and
2337Coffey [1], [2]:
2339.. math ::
2341 \gamma_n(a) = \frac{\log^n a}{2a} - \frac{\log^{n+1}(a)}{n+1} +
2342 \frac{2}{a} \Re \int_0^{\infty}
2343 \frac{(x/a-i)\log^n(a-ix)}{(1+x^2/a^2)(e^{2\pi x}-1)} dx.
2345For some reference values with `a = 1`, see e.g. [4].
2347**References**
23491. O. R. Ainsworth & L. W. Howell, "An integral representation of
2350 the generalized Euler-Mascheroni constants", NASA Technical
2351 Paper 2456 (1985),
2352 http://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19850014994_1985014994.pdf
23542. M. W. Coffey, "The Stieltjes constants, their relation to the
2355 `\eta_j` coefficients, and representation of the Hurwitz
2356 zeta function", arXiv:0706.0343v1 http://arxiv.org/abs/0706.0343
23583. http://mathworld.wolfram.com/StieltjesConstants.html
23604. http://pi.lacim.uqam.ca/piDATA/stieltjesgamma.txt
2362"""
2364gammaprod = r"""
2365Given iterables `a` and `b`, ``gammaprod(a, b)`` computes the
2366product / quotient of gamma functions:
2368.. math ::
2370 \frac{\Gamma(a_0) \Gamma(a_1) \cdots \Gamma(a_p)}
2371 {\Gamma(b_0) \Gamma(b_1) \cdots \Gamma(b_q)}
2373Unlike direct calls to :func:`~mpmath.gamma`, :func:`~mpmath.gammaprod` considers
2374the entire product as a limit and evaluates this limit properly if
2375any of the numerator or denominator arguments are nonpositive
2376integers such that poles of the gamma function are encountered.
2377That is, :func:`~mpmath.gammaprod` evaluates
2379.. math ::
2381 \lim_{\epsilon \to 0}
2382 \frac{\Gamma(a_0+\epsilon) \Gamma(a_1+\epsilon) \cdots
2383 \Gamma(a_p+\epsilon)}
2384 {\Gamma(b_0+\epsilon) \Gamma(b_1+\epsilon) \cdots
2385 \Gamma(b_q+\epsilon)}
2387In particular:
2389* If there are equally many poles in the numerator and the
2390 denominator, the limit is a rational number times the remaining,
2391 regular part of the product.
2393* If there are more poles in the numerator, :func:`~mpmath.gammaprod`
2394 returns ``+inf``.
2396* If there are more poles in the denominator, :func:`~mpmath.gammaprod`
2397 returns 0.
2399**Examples**
2401The reciprocal gamma function `1/\Gamma(x)` evaluated at `x = 0`::
2403 >>> from mpmath import *
2404 >>> mp.dps = 15
2405 >>> gammaprod([], [0])
2406 0.0
2408A limit::
2410 >>> gammaprod([-4], [-3])
2411 -0.25
2412 >>> limit(lambda x: gamma(x-1)/gamma(x), -3, direction=1)
2413 -0.25
2414 >>> limit(lambda x: gamma(x-1)/gamma(x), -3, direction=-1)
2415 -0.25
2417"""
2419beta = r"""
2420Computes the beta function,
2421`B(x,y) = \Gamma(x) \Gamma(y) / \Gamma(x+y)`.
2422The beta function is also commonly defined by the integral
2423representation
2425.. math ::
2427 B(x,y) = \int_0^1 t^{x-1} (1-t)^{y-1} \, dt
2429**Examples**
2431For integer and half-integer arguments where all three gamma
2432functions are finite, the beta function becomes either rational
2433number or a rational multiple of `\pi`::
2435 >>> from mpmath import *
2436 >>> mp.dps = 15; mp.pretty = True
2437 >>> beta(5, 2)
2438 0.0333333333333333
2439 >>> beta(1.5, 2)
2440 0.266666666666667
2441 >>> 16*beta(2.5, 1.5)
2442 3.14159265358979
2444Where appropriate, :func:`~mpmath.beta` evaluates limits. A pole
2445of the beta function is taken to result in ``+inf``::
2447 >>> beta(-0.5, 0.5)
2448 0.0
2449 >>> beta(-3, 3)
2450 -0.333333333333333
2451 >>> beta(-2, 3)
2452 +inf
2453 >>> beta(inf, 1)
2454 0.0
2455 >>> beta(inf, 0)
2456 nan
2458:func:`~mpmath.beta` supports complex numbers and arbitrary precision
2459evaluation::
2461 >>> beta(1, 2+j)
2462 (0.4 - 0.2j)
2463 >>> mp.dps = 25
2464 >>> beta(j,0.5)
2465 (1.079424249270925780135675 - 1.410032405664160838288752j)
2466 >>> mp.dps = 50
2467 >>> beta(pi, e)
2468 0.037890298781212201348153837138927165984170287886464
2470Various integrals can be computed by means of the
2471beta function::
2473 >>> mp.dps = 15
2474 >>> quad(lambda t: t**2.5*(1-t)**2, [0, 1])
2475 0.0230880230880231
2476 >>> beta(3.5, 3)
2477 0.0230880230880231
2478 >>> quad(lambda t: sin(t)**4 * sqrt(cos(t)), [0, pi/2])
2479 0.319504062596158
2480 >>> beta(2.5, 0.75)/2
2481 0.319504062596158
2483"""
2485betainc = r"""
2486``betainc(a, b, x1=0, x2=1, regularized=False)`` gives the generalized
2487incomplete beta function,
2489.. math ::
2491 I_{x_1}^{x_2}(a,b) = \int_{x_1}^{x_2} t^{a-1} (1-t)^{b-1} dt.
2493When `x_1 = 0, x_2 = 1`, this reduces to the ordinary (complete)
2494beta function `B(a,b)`; see :func:`~mpmath.beta`.
2496With the keyword argument ``regularized=True``, :func:`~mpmath.betainc`
2497computes the regularized incomplete beta function
2498`I_{x_1}^{x_2}(a,b) / B(a,b)`. This is the cumulative distribution of the
2499beta distribution with parameters `a`, `b`.
2501.. note :
2503 Implementations of the incomplete beta function in some other
2504 software uses a different argument order. For example, Mathematica uses the
2505 reversed argument order ``Beta[x1,x2,a,b]``. For the equivalent of SciPy's
2506 three-argument incomplete beta integral (implicitly with `x1 = 0`), use
2507 ``betainc(a,b,0,x2,regularized=True)``.
2509**Examples**
2511Verifying that :func:`~mpmath.betainc` computes the integral in the
2512definition::
2514 >>> from mpmath import *
2515 >>> mp.dps = 25; mp.pretty = True
2516 >>> x,y,a,b = 3, 4, 0, 6
2517 >>> betainc(x, y, a, b)
2518 -4010.4
2519 >>> quad(lambda t: t**(x-1) * (1-t)**(y-1), [a, b])
2520 -4010.4
2522The arguments may be arbitrary complex numbers::
2524 >>> betainc(0.75, 1-4j, 0, 2+3j)
2525 (0.2241657956955709603655887 + 0.3619619242700451992411724j)
2527With regularization::
2529 >>> betainc(1, 2, 0, 0.25, regularized=True)
2530 0.4375
2531 >>> betainc(pi, e, 0, 1, regularized=True) # Complete
2532 1.0
2534The beta integral satisfies some simple argument transformation
2535symmetries::
2537 >>> mp.dps = 15
2538 >>> betainc(2,3,4,5), -betainc(2,3,5,4), betainc(3,2,1-5,1-4)
2539 (56.0833333333333, 56.0833333333333, 56.0833333333333)
2541The beta integral can often be evaluated analytically. For integer and
2542rational arguments, the incomplete beta function typically reduces to a
2543simple algebraic-logarithmic expression::
2545 >>> mp.dps = 25
2546 >>> identify(chop(betainc(0, 0, 3, 4)))
2547 '-(log((9/8)))'
2548 >>> identify(betainc(2, 3, 4, 5))
2549 '(673/12)'
2550 >>> identify(betainc(1.5, 1, 1, 2))
2551 '((-12+sqrt(1152))/18)'
2553"""
2555binomial = r"""
2556Computes the binomial coefficient
2558.. math ::
2560 {n \choose k} = \frac{n!}{k!(n-k)!}.
2562The binomial coefficient gives the number of ways that `k` items
2563can be chosen from a set of `n` items. More generally, the binomial
2564coefficient is a well-defined function of arbitrary real or
2565complex `n` and `k`, via the gamma function.
2567**Examples**
2569Generate Pascal's triangle::
2571 >>> from mpmath import *
2572 >>> mp.dps = 15; mp.pretty = True
2573 >>> for n in range(5):
2574 ... nprint([binomial(n,k) for k in range(n+1)])
2575 ...
2576 [1.0]
2577 [1.0, 1.0]
2578 [1.0, 2.0, 1.0]
2579 [1.0, 3.0, 3.0, 1.0]
2580 [1.0, 4.0, 6.0, 4.0, 1.0]
2582There is 1 way to select 0 items from the empty set, and 0 ways to
2583select 1 item from the empty set::
2585 >>> binomial(0, 0)
2586 1.0
2587 >>> binomial(0, 1)
2588 0.0
2590:func:`~mpmath.binomial` supports large arguments::
2592 >>> binomial(10**20, 10**20-5)
2593 8.33333333333333e+97
2594 >>> binomial(10**20, 10**10)
2595 2.60784095465201e+104342944813
2597Nonintegral binomial coefficients find use in series
2598expansions::
2600 >>> nprint(taylor(lambda x: (1+x)**0.25, 0, 4))
2601 [1.0, 0.25, -0.09375, 0.0546875, -0.0375977]
2602 >>> nprint([binomial(0.25, k) for k in range(5)])
2603 [1.0, 0.25, -0.09375, 0.0546875, -0.0375977]
2605An integral representation::
2607 >>> n, k = 5, 3
2608 >>> f = lambda t: exp(-j*k*t)*(1+exp(j*t))**n
2609 >>> chop(quad(f, [-pi,pi])/(2*pi))
2610 10.0
2611 >>> binomial(n,k)
2612 10.0
2614"""
2616rf = r"""
2617Computes the rising factorial or Pochhammer symbol,
2619.. math ::
2621 x^{(n)} = x (x+1) \cdots (x+n-1) = \frac{\Gamma(x+n)}{\Gamma(x)}
2623where the rightmost expression is valid for nonintegral `n`.
2625**Examples**
2627For integral `n`, the rising factorial is a polynomial::
2629 >>> from mpmath import *
2630 >>> mp.dps = 15; mp.pretty = True
2631 >>> for n in range(5):
2632 ... nprint(taylor(lambda x: rf(x,n), 0, n))
2633 ...
2634 [1.0]
2635 [0.0, 1.0]
2636 [0.0, 1.0, 1.0]
2637 [0.0, 2.0, 3.0, 1.0]
2638 [0.0, 6.0, 11.0, 6.0, 1.0]
2640Evaluation is supported for arbitrary arguments::
2642 >>> rf(2+3j, 5.5)
2643 (-7202.03920483347 - 3777.58810701527j)
2644"""
2646ff = r"""
2647Computes the falling factorial,
2649.. math ::
2651 (x)_n = x (x-1) \cdots (x-n+1) = \frac{\Gamma(x+1)}{\Gamma(x-n+1)}
2653where the rightmost expression is valid for nonintegral `n`.
2655**Examples**
2657For integral `n`, the falling factorial is a polynomial::
2659 >>> from mpmath import *
2660 >>> mp.dps = 15; mp.pretty = True
2661 >>> for n in range(5):
2662 ... nprint(taylor(lambda x: ff(x,n), 0, n))
2663 ...
2664 [1.0]
2665 [0.0, 1.0]
2666 [0.0, -1.0, 1.0]
2667 [0.0, 2.0, -3.0, 1.0]
2668 [0.0, -6.0, 11.0, -6.0, 1.0]
2670Evaluation is supported for arbitrary arguments::
2672 >>> ff(2+3j, 5.5)
2673 (-720.41085888203 + 316.101124983878j)
2674"""
2676fac2 = r"""
2677Computes the double factorial `x!!`, defined for integers
2678`x > 0` by
2680.. math ::
2682 x!! = \begin{cases}
2683 1 \cdot 3 \cdots (x-2) \cdot x & x \;\mathrm{odd} \\
2684 2 \cdot 4 \cdots (x-2) \cdot x & x \;\mathrm{even}
2685 \end{cases}
2687and more generally by [1]
2689.. math ::
2691 x!! = 2^{x/2} \left(\frac{\pi}{2}\right)^{(\cos(\pi x)-1)/4}
2692 \Gamma\left(\frac{x}{2}+1\right).
2694**Examples**
2696The integer sequence of double factorials begins::
2698 >>> from mpmath import *
2699 >>> mp.dps = 15; mp.pretty = True
2700 >>> nprint([fac2(n) for n in range(10)])
2701 [1.0, 1.0, 2.0, 3.0, 8.0, 15.0, 48.0, 105.0, 384.0, 945.0]
2703For large `x`, double factorials follow a Stirling-like asymptotic
2704approximation::
2706 >>> x = mpf(10000)
2707 >>> fac2(x)
2708 5.97272691416282e+17830
2709 >>> sqrt(pi)*x**((x+1)/2)*exp(-x/2)
2710 5.97262736954392e+17830
2712The recurrence formula `x!! = x (x-2)!!` can be reversed to
2713define the double factorial of negative odd integers (but
2714not negative even integers)::
2716 >>> fac2(-1), fac2(-3), fac2(-5), fac2(-7)
2717 (1.0, -1.0, 0.333333333333333, -0.0666666666666667)
2718 >>> fac2(-2)
2719 Traceback (most recent call last):
2720 ...
2721 ValueError: gamma function pole
2723With the exception of the poles at negative even integers,
2724:func:`~mpmath.fac2` supports evaluation for arbitrary complex arguments.
2725The recurrence formula is valid generally::
2727 >>> fac2(pi+2j)
2728 (-1.3697207890154e-12 + 3.93665300979176e-12j)
2729 >>> (pi+2j)*fac2(pi-2+2j)
2730 (-1.3697207890154e-12 + 3.93665300979176e-12j)
2732Double factorials should not be confused with nested factorials,
2733which are immensely larger::
2735 >>> fac(fac(20))
2736 5.13805976125208e+43675043585825292774
2737 >>> fac2(20)
2738 3715891200.0
2740Double factorials appear, among other things, in series expansions
2741of Gaussian functions and the error function. Infinite series
2742include::
2744 >>> nsum(lambda k: 1/fac2(k), [0, inf])
2745 3.05940740534258
2746 >>> sqrt(e)*(1+sqrt(pi/2)*erf(sqrt(2)/2))
2747 3.05940740534258
2748 >>> nsum(lambda k: 2**k/fac2(2*k-1), [1, inf])
2749 4.06015693855741
2750 >>> e * erf(1) * sqrt(pi)
2751 4.06015693855741
2753A beautiful Ramanujan sum::
2755 >>> nsum(lambda k: (-1)**k*(fac2(2*k-1)/fac2(2*k))**3, [0,inf])
2756 0.90917279454693
2757 >>> (gamma('9/8')/gamma('5/4')/gamma('7/8'))**2
2758 0.90917279454693
2760**References**
27621. http://functions.wolfram.com/GammaBetaErf/Factorial2/27/01/0002/
27642. http://mathworld.wolfram.com/DoubleFactorial.html
2766"""
2768hyper = r"""
2769Evaluates the generalized hypergeometric function
2771.. math ::
2773 \,_pF_q(a_1,\ldots,a_p; b_1,\ldots,b_q; z) =
2774 \sum_{n=0}^\infty \frac{(a_1)_n (a_2)_n \ldots (a_p)_n}
2775 {(b_1)_n(b_2)_n\ldots(b_q)_n} \frac{z^n}{n!}
2777where `(x)_n` denotes the rising factorial (see :func:`~mpmath.rf`).
2779The parameters lists ``a_s`` and ``b_s`` may contain integers,
2780real numbers, complex numbers, as well as exact fractions given in
2781the form of tuples `(p, q)`. :func:`~mpmath.hyper` is optimized to handle
2782integers and fractions more efficiently than arbitrary
2783floating-point parameters (since rational parameters are by
2784far the most common).
2786**Examples**
2788Verifying that :func:`~mpmath.hyper` gives the sum in the definition, by
2789comparison with :func:`~mpmath.nsum`::
2791 >>> from mpmath import *
2792 >>> mp.dps = 25; mp.pretty = True
2793 >>> a,b,c,d = 2,3,4,5
2794 >>> x = 0.25
2795 >>> hyper([a,b],[c,d],x)
2796 1.078903941164934876086237
2797 >>> fn = lambda n: rf(a,n)*rf(b,n)/rf(c,n)/rf(d,n)*x**n/fac(n)
2798 >>> nsum(fn, [0, inf])
2799 1.078903941164934876086237
2801The parameters can be any combination of integers, fractions,
2802floats and complex numbers::
2804 >>> a, b, c, d, e = 1, (-1,2), pi, 3+4j, (2,3)
2805 >>> x = 0.2j
2806 >>> hyper([a,b],[c,d,e],x)
2807 (0.9923571616434024810831887 - 0.005753848733883879742993122j)
2808 >>> b, e = -0.5, mpf(2)/3
2809 >>> fn = lambda n: rf(a,n)*rf(b,n)/rf(c,n)/rf(d,n)/rf(e,n)*x**n/fac(n)
2810 >>> nsum(fn, [0, inf])
2811 (0.9923571616434024810831887 - 0.005753848733883879742993122j)
2813The `\,_0F_0` and `\,_1F_0` series are just elementary functions::
2815 >>> a, z = sqrt(2), +pi
2816 >>> hyper([],[],z)
2817 23.14069263277926900572909
2818 >>> exp(z)
2819 23.14069263277926900572909
2820 >>> hyper([a],[],z)
2821 (-0.09069132879922920160334114 + 0.3283224323946162083579656j)
2822 >>> (1-z)**(-a)
2823 (-0.09069132879922920160334114 + 0.3283224323946162083579656j)
2825If any `a_k` coefficient is a nonpositive integer, the series terminates
2826into a finite polynomial::
2828 >>> hyper([1,1,1,-3],[2,5],1)
2829 0.7904761904761904761904762
2830 >>> identify(_)
2831 '(83/105)'
2833If any `b_k` is a nonpositive integer, the function is undefined (unless the
2834series terminates before the division by zero occurs)::
2836 >>> hyper([1,1,1,-3],[-2,5],1)
2837 Traceback (most recent call last):
2838 ...
2839 ZeroDivisionError: pole in hypergeometric series
2840 >>> hyper([1,1,1,-1],[-2,5],1)
2841 1.1
2843Except for polynomial cases, the radius of convergence `R` of the hypergeometric
2844series is either `R = \infty` (if `p \le q`), `R = 1` (if `p = q+1`), or
2845`R = 0` (if `p > q+1`).
2847The analytic continuations of the functions with `p = q+1`, i.e. `\,_2F_1`,
2848`\,_3F_2`, `\,_4F_3`, etc, are all implemented and therefore these functions
2849can be evaluated for `|z| \ge 1`. The shortcuts :func:`~mpmath.hyp2f1`, :func:`~mpmath.hyp3f2`
2850are available to handle the most common cases (see their documentation),
2851but functions of higher degree are also supported via :func:`~mpmath.hyper`::
2853 >>> hyper([1,2,3,4], [5,6,7], 1) # 4F3 at finite-valued branch point
2854 1.141783505526870731311423
2855 >>> hyper([4,5,6,7], [1,2,3], 1) # 4F3 at pole
2856 +inf
2857 >>> hyper([1,2,3,4,5], [6,7,8,9], 10) # 5F4
2858 (1.543998916527972259717257 - 0.5876309929580408028816365j)
2859 >>> hyper([1,2,3,4,5,6], [7,8,9,10,11], 1j) # 6F5
2860 (0.9996565821853579063502466 + 0.0129721075905630604445669j)
2862Near `z = 1` with noninteger parameters::
2864 >>> hyper(['1/3',1,'3/2',2], ['1/5','11/6','41/8'], 1)
2865 2.219433352235586121250027
2866 >>> hyper(['1/3',1,'3/2',2], ['1/5','11/6','5/4'], 1)
2867 +inf
2868 >>> eps1 = extradps(6)(lambda: 1 - mpf('1e-6'))()
2869 >>> hyper(['1/3',1,'3/2',2], ['1/5','11/6','5/4'], eps1)
2870 2923978034.412973409330956
2872Please note that, as currently implemented, evaluation of `\,_pF_{p-1}`
2873with `p \ge 3` may be slow or inaccurate when `|z-1|` is small,
2874for some parameter values.
2876Evaluation may be aborted if convergence appears to be too slow.
2877The optional ``maxterms`` (limiting the number of series terms) and ``maxprec``
2878(limiting the internal precision) keyword arguments can be used
2879to control evaluation::
2881 >>> hyper([1,2,3], [4,5,6], 10000)
2882 Traceback (most recent call last):
2883 ...
2884 NoConvergence: Hypergeometric series converges too slowly. Try increasing maxterms.
2885 >>> hyper([1,2,3], [4,5,6], 10000, maxterms=10**6)
2886 7.622806053177969474396918e+4310
2888Additional options include ``force_series`` (which forces direct use of
2889a hypergeometric series even if another evaluation method might work better)
2890and ``asymp_tol`` which controls the target tolerance for using
2891asymptotic series.
2893When `p > q+1`, ``hyper`` computes the (iterated) Borel sum of the divergent
2894series. For `\,_2F_0` the Borel sum has an analytic solution and can be
2895computed efficiently (see :func:`~mpmath.hyp2f0`). For higher degrees, the functions
2896is evaluated first by attempting to sum it directly as an asymptotic
2897series (this only works for tiny `|z|`), and then by evaluating the Borel
2898regularized sum using numerical integration. Except for
2899special parameter combinations, this can be extremely slow.
2901 >>> hyper([1,1], [], 0.5) # regularization of 2F0
2902 (1.340965419580146562086448 + 0.8503366631752726568782447j)
2903 >>> hyper([1,1,1,1], [1], 0.5) # regularization of 4F1
2904 (1.108287213689475145830699 + 0.5327107430640678181200491j)
2906With the following magnitude of argument, the asymptotic series for `\,_3F_1`
2907gives only a few digits. Using Borel summation, ``hyper`` can produce
2908a value with full accuracy::
2910 >>> mp.dps = 15
2911 >>> hyper([2,0.5,4], [5.25], '0.08', force_series=True)
2912 Traceback (most recent call last):
2913 ...
2914 NoConvergence: Hypergeometric series converges too slowly. Try increasing maxterms.
2915 >>> hyper([2,0.5,4], [5.25], '0.08', asymp_tol=1e-4)
2916 1.0725535790737
2917 >>> hyper([2,0.5,4], [5.25], '0.08')
2918 (1.07269542893559 + 5.54668863216891e-5j)
2919 >>> hyper([2,0.5,4], [5.25], '-0.08', asymp_tol=1e-4)
2920 0.946344925484879
2921 >>> hyper([2,0.5,4], [5.25], '-0.08')
2922 0.946312503737771
2923 >>> mp.dps = 25
2924 >>> hyper([2,0.5,4], [5.25], '-0.08')
2925 0.9463125037377662296700858
2927Note that with the positive `z` value, there is a complex part in the
2928correct result, which falls below the tolerance of the asymptotic series.
2930By default, a parameter that appears in both ``a_s`` and ``b_s`` will be removed
2931unless it is a nonpositive integer. This generally speeds up evaluation
2932by producing a hypergeometric function of lower order.
2933This optimization can be disabled by passing ``eliminate=False``.
2935 >>> hyper([1,2,3], [4,5,3], 10000)
2936 1.268943190440206905892212e+4321
2937 >>> hyper([1,2,3], [4,5,3], 10000, eliminate=False)
2938 Traceback (most recent call last):
2939 ...
2940 NoConvergence: Hypergeometric series converges too slowly. Try increasing maxterms.
2941 >>> hyper([1,2,3], [4,5,3], 10000, eliminate=False, maxterms=10**6)
2942 1.268943190440206905892212e+4321
2944If a nonpositive integer `-n` appears in both ``a_s`` and ``b_s``, this parameter
2945cannot be unambiguously removed since it creates a term 0 / 0.
2946In this case the hypergeometric series is understood to terminate before
2947the division by zero occurs. This convention is consistent with Mathematica.
2948An alternative convention of eliminating the parameters can be toggled
2949with ``eliminate_all=True``:
2951 >>> hyper([2,-1], [-1], 3)
2952 7.0
2953 >>> hyper([2,-1], [-1], 3, eliminate_all=True)
2954 0.25
2955 >>> hyper([2], [], 3)
2956 0.25
2958"""
2960hypercomb = r"""
2961Computes a weighted combination of hypergeometric functions
2963.. math ::
2965 \sum_{r=1}^N \left[ \prod_{k=1}^{l_r} {w_{r,k}}^{c_{r,k}}
2966 \frac{\prod_{k=1}^{m_r} \Gamma(\alpha_{r,k})}{\prod_{k=1}^{n_r}
2967 \Gamma(\beta_{r,k})}
2968 \,_{p_r}F_{q_r}(a_{r,1},\ldots,a_{r,p}; b_{r,1},
2969 \ldots, b_{r,q}; z_r)\right].
2971Typically the parameters are linear combinations of a small set of base
2972parameters; :func:`~mpmath.hypercomb` permits computing a correct value in
2973the case that some of the `\alpha`, `\beta`, `b` turn out to be
2974nonpositive integers, or if division by zero occurs for some `w^c`,
2975assuming that there are opposing singularities that cancel out.
2976The limit is computed by evaluating the function with the base
2977parameters perturbed, at a higher working precision.
2979The first argument should be a function that takes the perturbable
2980base parameters ``params`` as input and returns `N` tuples
2981``(w, c, alpha, beta, a, b, z)``, where the coefficients ``w``, ``c``,
2982gamma factors ``alpha``, ``beta``, and hypergeometric coefficients
2983``a``, ``b`` each should be lists of numbers, and ``z`` should be a single
2984number.
2986**Examples**
2988The following evaluates
2990.. math ::
2992 (a-1) \frac{\Gamma(a-3)}{\Gamma(a-4)} \,_1F_1(a,a-1,z) = e^z(a-4)(a+z-1)
2994with `a=1, z=3`. There is a zero factor, two gamma function poles, and
2995the 1F1 function is singular; all singularities cancel out to give a finite
2996value::
2998 >>> from mpmath import *
2999 >>> mp.dps = 15; mp.pretty = True
3000 >>> hypercomb(lambda a: [([a-1],[1],[a-3],[a-4],[a],[a-1],3)], [1])
3001 -180.769832308689
3002 >>> -9*exp(3)
3003 -180.769832308689
3005"""
3007hyp0f1 = r"""
3008Gives the hypergeometric function `\,_0F_1`, sometimes known as the
3009confluent limit function, defined as
3011.. math ::
3013 \,_0F_1(a,z) = \sum_{k=0}^{\infty} \frac{1}{(a)_k} \frac{z^k}{k!}.
3015This function satisfies the differential equation `z f''(z) + a f'(z) = f(z)`,
3016and is related to the Bessel function of the first kind (see :func:`~mpmath.besselj`).
3018``hyp0f1(a,z)`` is equivalent to ``hyper([],[a],z)``; see documentation for
3019:func:`~mpmath.hyper` for more information.
3021**Examples**
3023Evaluation for arbitrary arguments::
3025 >>> from mpmath import *
3026 >>> mp.dps = 25; mp.pretty = True
3027 >>> hyp0f1(2, 0.25)
3028 1.130318207984970054415392
3029 >>> hyp0f1((1,2), 1234567)
3030 6.27287187546220705604627e+964
3031 >>> hyp0f1(3+4j, 1000000j)
3032 (3.905169561300910030267132e+606 + 3.807708544441684513934213e+606j)
3034Evaluation is supported for arbitrarily large values of `z`,
3035using asymptotic expansions::
3037 >>> hyp0f1(1, 10**50)
3038 2.131705322874965310390701e+8685889638065036553022565
3039 >>> hyp0f1(1, -10**50)
3040 1.115945364792025420300208e-13
3042Verifying the differential equation::
3044 >>> a = 2.5
3045 >>> f = lambda z: hyp0f1(a,z)
3046 >>> for z in [0, 10, 3+4j]:
3047 ... chop(z*diff(f,z,2) + a*diff(f,z) - f(z))
3048 ...
3049 0.0
3050 0.0
3051 0.0
3053"""
3055hyp1f1 = r"""
3056Gives the confluent hypergeometric function of the first kind,
3058.. math ::
3060 \,_1F_1(a,b,z) = \sum_{k=0}^{\infty} \frac{(a)_k}{(b)_k} \frac{z^k}{k!},
3062also known as Kummer's function and sometimes denoted by `M(a,b,z)`. This
3063function gives one solution to the confluent (Kummer's) differential equation
3065.. math ::
3067 z f''(z) + (b-z) f'(z) - af(z) = 0.
3069A second solution is given by the `U` function; see :func:`~mpmath.hyperu`.
3070Solutions are also given in an alternate form by the Whittaker
3071functions (:func:`~mpmath.whitm`, :func:`~mpmath.whitw`).
3073``hyp1f1(a,b,z)`` is equivalent
3074to ``hyper([a],[b],z)``; see documentation for :func:`~mpmath.hyper` for more
3075information.
3077**Examples**
3079Evaluation for real and complex values of the argument `z`, with
3080fixed parameters `a = 2, b = -1/3`::
3082 >>> from mpmath import *
3083 >>> mp.dps = 25; mp.pretty = True
3084 >>> hyp1f1(2, (-1,3), 3.25)
3085 -2815.956856924817275640248
3086 >>> hyp1f1(2, (-1,3), -3.25)
3087 -1.145036502407444445553107
3088 >>> hyp1f1(2, (-1,3), 1000)
3089 -8.021799872770764149793693e+441
3090 >>> hyp1f1(2, (-1,3), -1000)
3091 0.000003131987633006813594535331
3092 >>> hyp1f1(2, (-1,3), 100+100j)
3093 (-3.189190365227034385898282e+48 - 1.106169926814270418999315e+49j)
3095Parameters may be complex::
3097 >>> hyp1f1(2+3j, -1+j, 10j)
3098 (261.8977905181045142673351 + 160.8930312845682213562172j)
3100Arbitrarily large values of `z` are supported::
3102 >>> hyp1f1(3, 4, 10**20)
3103 3.890569218254486878220752e+43429448190325182745
3104 >>> hyp1f1(3, 4, -10**20)
3105 6.0e-60
3106 >>> hyp1f1(3, 4, 10**20*j)
3107 (-1.935753855797342532571597e-20 - 2.291911213325184901239155e-20j)
3109Verifying the differential equation::
3111 >>> a, b = 1.5, 2
3112 >>> f = lambda z: hyp1f1(a,b,z)
3113 >>> for z in [0, -10, 3, 3+4j]:
3114 ... chop(z*diff(f,z,2) + (b-z)*diff(f,z) - a*f(z))
3115 ...
3116 0.0
3117 0.0
3118 0.0
3119 0.0
3121An integral representation::
3123 >>> a, b = 1.5, 3
3124 >>> z = 1.5
3125 >>> hyp1f1(a,b,z)
3126 2.269381460919952778587441
3127 >>> g = lambda t: exp(z*t)*t**(a-1)*(1-t)**(b-a-1)
3128 >>> gammaprod([b],[a,b-a])*quad(g, [0,1])
3129 2.269381460919952778587441
3132"""
3134hyp1f2 = r"""
3135Gives the hypergeometric function `\,_1F_2(a_1,a_2;b_1,b_2; z)`.
3136The call ``hyp1f2(a1,b1,b2,z)`` is equivalent to
3137``hyper([a1],[b1,b2],z)``.
3139Evaluation works for complex and arbitrarily large arguments::
3141 >>> from mpmath import *
3142 >>> mp.dps = 25; mp.pretty = True
3143 >>> a, b, c = 1.5, (-1,3), 2.25
3144 >>> hyp1f2(a, b, c, 10**20)
3145 -1.159388148811981535941434e+8685889639
3146 >>> hyp1f2(a, b, c, -10**20)
3147 -12.60262607892655945795907
3148 >>> hyp1f2(a, b, c, 10**20*j)
3149 (4.237220401382240876065501e+6141851464 - 2.950930337531768015892987e+6141851464j)
3150 >>> hyp1f2(2+3j, -2j, 0.5j, 10-20j)
3151 (135881.9905586966432662004 - 86681.95885418079535738828j)
3153"""
3155hyp2f2 = r"""
3156Gives the hypergeometric function `\,_2F_2(a_1,a_2;b_1,b_2; z)`.
3157The call ``hyp2f2(a1,a2,b1,b2,z)`` is equivalent to
3158``hyper([a1,a2],[b1,b2],z)``.
3160Evaluation works for complex and arbitrarily large arguments::
3162 >>> from mpmath import *
3163 >>> mp.dps = 25; mp.pretty = True
3164 >>> a, b, c, d = 1.5, (-1,3), 2.25, 4
3165 >>> hyp2f2(a, b, c, d, 10**20)
3166 -5.275758229007902299823821e+43429448190325182663
3167 >>> hyp2f2(a, b, c, d, -10**20)
3168 2561445.079983207701073448
3169 >>> hyp2f2(a, b, c, d, 10**20*j)
3170 (2218276.509664121194836667 - 1280722.539991603850462856j)
3171 >>> hyp2f2(2+3j, -2j, 0.5j, 4j, 10-20j)
3172 (80500.68321405666957342788 - 20346.82752982813540993502j)
3174"""
3176hyp2f3 = r"""
3177Gives the hypergeometric function `\,_2F_3(a_1,a_2;b_1,b_2,b_3; z)`.
3178The call ``hyp2f3(a1,a2,b1,b2,b3,z)`` is equivalent to
3179``hyper([a1,a2],[b1,b2,b3],z)``.
3181Evaluation works for arbitrarily large arguments::
3183 >>> from mpmath import *
3184 >>> mp.dps = 25; mp.pretty = True
3185 >>> a1,a2,b1,b2,b3 = 1.5, (-1,3), 2.25, 4, (1,5)
3186 >>> hyp2f3(a1,a2,b1,b2,b3,10**20)
3187 -4.169178177065714963568963e+8685889590
3188 >>> hyp2f3(a1,a2,b1,b2,b3,-10**20)
3189 7064472.587757755088178629
3190 >>> hyp2f3(a1,a2,b1,b2,b3,10**20*j)
3191 (-5.163368465314934589818543e+6141851415 + 1.783578125755972803440364e+6141851416j)
3192 >>> hyp2f3(2+3j, -2j, 0.5j, 4j, -1-j, 10-20j)
3193 (-2280.938956687033150740228 + 13620.97336609573659199632j)
3194 >>> hyp2f3(2+3j, -2j, 0.5j, 4j, -1-j, 10000000-20000000j)
3195 (4.849835186175096516193e+3504 - 3.365981529122220091353633e+3504j)
3197"""
3199hyp2f1 = r"""
3200Gives the Gauss hypergeometric function `\,_2F_1` (often simply referred to as
3201*the* hypergeometric function), defined for `|z| < 1` as
3203.. math ::
3205 \,_2F_1(a,b,c,z) = \sum_{k=0}^{\infty}
3206 \frac{(a)_k (b)_k}{(c)_k} \frac{z^k}{k!}.
3208and for `|z| \ge 1` by analytic continuation, with a branch cut on `(1, \infty)`
3209when necessary.
3211Special cases of this function include many of the orthogonal polynomials as
3212well as the incomplete beta function and other functions. Properties of the
3213Gauss hypergeometric function are documented comprehensively in many references,
3214for example Abramowitz & Stegun, section 15.
3216The implementation supports the analytic continuation as well as evaluation
3217close to the unit circle where `|z| \approx 1`. The syntax ``hyp2f1(a,b,c,z)``
3218is equivalent to ``hyper([a,b],[c],z)``.
3220**Examples**
3222Evaluation with `z` inside, outside and on the unit circle, for
3223fixed parameters::
3225 >>> from mpmath import *
3226 >>> mp.dps = 25; mp.pretty = True
3227 >>> hyp2f1(2, (1,2), 4, 0.75)
3228 1.303703703703703703703704
3229 >>> hyp2f1(2, (1,2), 4, -1.75)
3230 0.7431290566046919177853916
3231 >>> hyp2f1(2, (1,2), 4, 1.75)
3232 (1.418075801749271137026239 - 1.114976146679907015775102j)
3233 >>> hyp2f1(2, (1,2), 4, 1)
3234 1.6
3235 >>> hyp2f1(2, (1,2), 4, -1)
3236 0.8235498012182875315037882
3237 >>> hyp2f1(2, (1,2), 4, j)
3238 (0.9144026291433065674259078 + 0.2050415770437884900574923j)
3239 >>> hyp2f1(2, (1,2), 4, 2+j)
3240 (0.9274013540258103029011549 + 0.7455257875808100868984496j)
3241 >>> hyp2f1(2, (1,2), 4, 0.25j)
3242 (0.9931169055799728251931672 + 0.06154836525312066938147793j)
3244Evaluation with complex parameter values::
3246 >>> hyp2f1(1+j, 0.75, 10j, 1+5j)
3247 (0.8834833319713479923389638 + 0.7053886880648105068343509j)
3249Evaluation with `z = 1`::
3251 >>> hyp2f1(-2.5, 3.5, 1.5, 1)
3252 0.0
3253 >>> hyp2f1(-2.5, 3, 4, 1)
3254 0.06926406926406926406926407
3255 >>> hyp2f1(2, 3, 4, 1)
3256 +inf
3258Evaluation for huge arguments::
3260 >>> hyp2f1((-1,3), 1.75, 4, '1e100')
3261 (7.883714220959876246415651e+32 + 1.365499358305579597618785e+33j)
3262 >>> hyp2f1((-1,3), 1.75, 4, '1e1000000')
3263 (7.883714220959876246415651e+333332 + 1.365499358305579597618785e+333333j)
3264 >>> hyp2f1((-1,3), 1.75, 4, '1e1000000j')
3265 (1.365499358305579597618785e+333333 - 7.883714220959876246415651e+333332j)
3267An integral representation::
3269 >>> a,b,c,z = -0.5, 1, 2.5, 0.25
3270 >>> g = lambda t: t**(b-1) * (1-t)**(c-b-1) * (1-t*z)**(-a)
3271 >>> gammaprod([c],[b,c-b]) * quad(g, [0,1])
3272 0.9480458814362824478852618
3273 >>> hyp2f1(a,b,c,z)
3274 0.9480458814362824478852618
3276Verifying the hypergeometric differential equation::
3278 >>> f = lambda z: hyp2f1(a,b,c,z)
3279 >>> chop(z*(1-z)*diff(f,z,2) + (c-(a+b+1)*z)*diff(f,z) - a*b*f(z))
3280 0.0
3282"""
3284hyp3f2 = r"""
3285Gives the generalized hypergeometric function `\,_3F_2`, defined for `|z| < 1`
3286as
3288.. math ::
3290 \,_3F_2(a_1,a_2,a_3,b_1,b_2,z) = \sum_{k=0}^{\infty}
3291 \frac{(a_1)_k (a_2)_k (a_3)_k}{(b_1)_k (b_2)_k} \frac{z^k}{k!}.
3293and for `|z| \ge 1` by analytic continuation. The analytic structure of this
3294function is similar to that of `\,_2F_1`, generally with a singularity at
3295`z = 1` and a branch cut on `(1, \infty)`.
3297Evaluation is supported inside, on, and outside
3298the circle of convergence `|z| = 1`::
3300 >>> from mpmath import *
3301 >>> mp.dps = 25; mp.pretty = True
3302 >>> hyp3f2(1,2,3,4,5,0.25)
3303 1.083533123380934241548707
3304 >>> hyp3f2(1,2+2j,3,4,5,-10+10j)
3305 (0.1574651066006004632914361 - 0.03194209021885226400892963j)
3306 >>> hyp3f2(1,2,3,4,5,-10)
3307 0.3071141169208772603266489
3308 >>> hyp3f2(1,2,3,4,5,10)
3309 (-0.4857045320523947050581423 - 0.5988311440454888436888028j)
3310 >>> hyp3f2(0.25,1,1,2,1.5,1)
3311 1.157370995096772047567631
3312 >>> (8-pi-2*ln2)/3
3313 1.157370995096772047567631
3314 >>> hyp3f2(1+j,0.5j,2,1,-2j,-1)
3315 (1.74518490615029486475959 + 0.1454701525056682297614029j)
3316 >>> hyp3f2(1+j,0.5j,2,1,-2j,sqrt(j))
3317 (0.9829816481834277511138055 - 0.4059040020276937085081127j)
3318 >>> hyp3f2(-3,2,1,-5,4,1)
3319 1.41
3320 >>> hyp3f2(-3,2,1,-5,4,2)
3321 2.12
3323Evaluation very close to the unit circle::
3325 >>> hyp3f2(1,2,3,4,5,'1.0001')
3326 (1.564877796743282766872279 - 3.76821518787438186031973e-11j)
3327 >>> hyp3f2(1,2,3,4,5,'1+0.0001j')
3328 (1.564747153061671573212831 + 0.0001305757570366084557648482j)
3329 >>> hyp3f2(1,2,3,4,5,'0.9999')
3330 1.564616644881686134983664
3331 >>> hyp3f2(1,2,3,4,5,'-0.9999')
3332 0.7823896253461678060196207
3334.. note ::
3336 Evaluation for `|z-1|` small can currently be inaccurate or slow
3337 for some parameter combinations.
3339For various parameter combinations, `\,_3F_2` admits representation in terms
3340of hypergeometric functions of lower degree, or in terms of
3341simpler functions::
3343 >>> for a, b, z in [(1,2,-1), (2,0.5,1)]:
3344 ... hyp2f1(a,b,a+b+0.5,z)**2
3345 ... hyp3f2(2*a,a+b,2*b,a+b+0.5,2*a+2*b,z)
3346 ...
3347 0.4246104461966439006086308
3348 0.4246104461966439006086308
3349 7.111111111111111111111111
3350 7.111111111111111111111111
3352 >>> z = 2+3j
3353 >>> hyp3f2(0.5,1,1.5,2,2,z)
3354 (0.7621440939243342419729144 + 0.4249117735058037649915723j)
3355 >>> 4*(pi-2*ellipe(z))/(pi*z)
3356 (0.7621440939243342419729144 + 0.4249117735058037649915723j)
3358"""
3360hyperu = r"""
3361Gives the Tricomi confluent hypergeometric function `U`, also known as
3362the Kummer or confluent hypergeometric function of the second kind. This
3363function gives a second linearly independent solution to the confluent
3364hypergeometric differential equation (the first is provided by `\,_1F_1` --
3365see :func:`~mpmath.hyp1f1`).
3367**Examples**
3369Evaluation for arbitrary complex arguments::
3371 >>> from mpmath import *
3372 >>> mp.dps = 25; mp.pretty = True
3373 >>> hyperu(2,3,4)
3374 0.0625
3375 >>> hyperu(0.25, 5, 1000)
3376 0.1779949416140579573763523
3377 >>> hyperu(0.25, 5, -1000)
3378 (0.1256256609322773150118907 - 0.1256256609322773150118907j)
3380The `U` function may be singular at `z = 0`::
3382 >>> hyperu(1.5, 2, 0)
3383 +inf
3384 >>> hyperu(1.5, -2, 0)
3385 0.1719434921288400112603671
3387Verifying the differential equation::
3389 >>> a, b = 1.5, 2
3390 >>> f = lambda z: hyperu(a,b,z)
3391 >>> for z in [-10, 3, 3+4j]:
3392 ... chop(z*diff(f,z,2) + (b-z)*diff(f,z) - a*f(z))
3393 ...
3394 0.0
3395 0.0
3396 0.0
3398An integral representation::
3400 >>> a,b,z = 2, 3.5, 4.25
3401 >>> hyperu(a,b,z)
3402 0.06674960718150520648014567
3403 >>> quad(lambda t: exp(-z*t)*t**(a-1)*(1+t)**(b-a-1),[0,inf]) / gamma(a)
3404 0.06674960718150520648014567
3407[1] http://people.math.sfu.ca/~cbm/aands/page_504.htm
3408"""
3410hyp2f0 = r"""
3411Gives the hypergeometric function `\,_2F_0`, defined formally by the
3412series
3414.. math ::
3416 \,_2F_0(a,b;;z) = \sum_{n=0}^{\infty} (a)_n (b)_n \frac{z^n}{n!}.
3418This series usually does not converge. For small enough `z`, it can be viewed
3419as an asymptotic series that may be summed directly with an appropriate
3420truncation. When this is not the case, :func:`~mpmath.hyp2f0` gives a regularized sum,
3421or equivalently, it uses a representation in terms of the
3422hypergeometric U function [1]. The series also converges when either `a` or `b`
3423is a nonpositive integer, as it then terminates into a polynomial
3424after `-a` or `-b` terms.
3426**Examples**
3428Evaluation is supported for arbitrary complex arguments::
3430 >>> from mpmath import *
3431 >>> mp.dps = 25; mp.pretty = True
3432 >>> hyp2f0((2,3), 1.25, -100)
3433 0.07095851870980052763312791
3434 >>> hyp2f0((2,3), 1.25, 100)
3435 (-0.03254379032170590665041131 + 0.07269254613282301012735797j)
3436 >>> hyp2f0(-0.75, 1-j, 4j)
3437 (-0.3579987031082732264862155 - 3.052951783922142735255881j)
3439Even with real arguments, the regularized value of 2F0 is often complex-valued,
3440but the imaginary part decreases exponentially as `z \to 0`. In the following
3441example, the first call uses complex evaluation while the second has a small
3442enough `z` to evaluate using the direct series and thus the returned value
3443is strictly real (this should be taken to indicate that the imaginary
3444part is less than ``eps``)::
3446 >>> mp.dps = 15
3447 >>> hyp2f0(1.5, 0.5, 0.05)
3448 (1.04166637647907 + 8.34584913683906e-8j)
3449 >>> hyp2f0(1.5, 0.5, 0.0005)
3450 1.00037535207621
3452The imaginary part can be retrieved by increasing the working precision::
3454 >>> mp.dps = 80
3455 >>> nprint(hyp2f0(1.5, 0.5, 0.009).imag)
3456 1.23828e-46
3458In the polynomial case (the series terminating), 2F0 can evaluate exactly::
3460 >>> mp.dps = 15
3461 >>> hyp2f0(-6,-6,2)
3462 291793.0
3463 >>> identify(hyp2f0(-2,1,0.25))
3464 '(5/8)'
3466The coefficients of the polynomials can be recovered using Taylor expansion::
3468 >>> nprint(taylor(lambda x: hyp2f0(-3,0.5,x), 0, 10))
3469 [1.0, -1.5, 2.25, -1.875, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
3470 >>> nprint(taylor(lambda x: hyp2f0(-4,0.5,x), 0, 10))
3471 [1.0, -2.0, 4.5, -7.5, 6.5625, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
3474[1] http://people.math.sfu.ca/~cbm/aands/page_504.htm
3475"""
3478gammainc = r"""
3479``gammainc(z, a=0, b=inf)`` computes the (generalized) incomplete
3480gamma function with integration limits `[a, b]`:
3482.. math ::
3484 \Gamma(z,a,b) = \int_a^b t^{z-1} e^{-t} \, dt
3486The generalized incomplete gamma function reduces to the
3487following special cases when one or both endpoints are fixed:
3489* `\Gamma(z,0,\infty)` is the standard ("complete")
3490 gamma function, `\Gamma(z)` (available directly
3491 as the mpmath function :func:`~mpmath.gamma`)
3492* `\Gamma(z,a,\infty)` is the "upper" incomplete gamma
3493 function, `\Gamma(z,a)`
3494* `\Gamma(z,0,b)` is the "lower" incomplete gamma
3495 function, `\gamma(z,b)`.
3497Of course, we have
3498`\Gamma(z,0,x) + \Gamma(z,x,\infty) = \Gamma(z)`
3499for all `z` and `x`.
3501Note however that some authors reverse the order of the
3502arguments when defining the lower and upper incomplete
3503gamma function, so one should be careful to get the correct
3504definition.
3506If also given the keyword argument ``regularized=True``,
3507:func:`~mpmath.gammainc` computes the "regularized" incomplete gamma
3508function
3510.. math ::
3512 P(z,a,b) = \frac{\Gamma(z,a,b)}{\Gamma(z)}.
3514**Examples**
3516We can compare with numerical quadrature to verify that
3517:func:`~mpmath.gammainc` computes the integral in the definition::
3519 >>> from mpmath import *
3520 >>> mp.dps = 25; mp.pretty = True
3521 >>> gammainc(2+3j, 4, 10)
3522 (0.00977212668627705160602312 - 0.0770637306312989892451977j)
3523 >>> quad(lambda t: t**(2+3j-1) * exp(-t), [4, 10])
3524 (0.00977212668627705160602312 - 0.0770637306312989892451977j)
3526Argument symmetries follow directly from the integral definition::
3528 >>> gammainc(3, 4, 5) + gammainc(3, 5, 4)
3529 0.0
3530 >>> gammainc(3,0,2) + gammainc(3,2,4); gammainc(3,0,4)
3531 1.523793388892911312363331
3532 1.523793388892911312363331
3533 >>> findroot(lambda z: gammainc(2,z,3), 1)
3534 3.0
3536Evaluation for arbitrarily large arguments::
3538 >>> gammainc(10, 100)
3539 4.083660630910611272288592e-26
3540 >>> gammainc(10, 10000000000000000)
3541 5.290402449901174752972486e-4342944819032375
3542 >>> gammainc(3+4j, 1000000+1000000j)
3543 (-1.257913707524362408877881e-434284 + 2.556691003883483531962095e-434284j)
3545Evaluation of a generalized incomplete gamma function automatically chooses
3546the representation that gives a more accurate result, depending on which
3547parameter is larger::
3549 >>> gammainc(10000000, 3) - gammainc(10000000, 2) # Bad
3550 0.0
3551 >>> gammainc(10000000, 2, 3) # Good
3552 1.755146243738946045873491e+4771204
3553 >>> gammainc(2, 0, 100000001) - gammainc(2, 0, 100000000) # Bad
3554 0.0
3555 >>> gammainc(2, 100000000, 100000001) # Good
3556 4.078258353474186729184421e-43429441
3558The incomplete gamma functions satisfy simple recurrence
3559relations::
3561 >>> mp.dps = 25
3562 >>> z, a = mpf(3.5), mpf(2)
3563 >>> gammainc(z+1, a); z*gammainc(z,a) + a**z*exp(-a)
3564 10.60130296933533459267329
3565 10.60130296933533459267329
3566 >>> gammainc(z+1,0,a); z*gammainc(z,0,a) - a**z*exp(-a)
3567 1.030425427232114336470932
3568 1.030425427232114336470932
3570Evaluation at integers and poles::
3572 >>> gammainc(-3, -4, -5)
3573 (-0.2214577048967798566234192 + 0.0j)
3574 >>> gammainc(-3, 0, 5)
3575 +inf
3577If `z` is an integer, the recurrence reduces the incomplete gamma
3578function to `P(a) \exp(-a) + Q(b) \exp(-b)` where `P` and
3579`Q` are polynomials::
3581 >>> gammainc(1, 2); exp(-2)
3582 0.1353352832366126918939995
3583 0.1353352832366126918939995
3584 >>> mp.dps = 50
3585 >>> identify(gammainc(6, 1, 2), ['exp(-1)', 'exp(-2)'])
3586 '(326*exp(-1) + (-872)*exp(-2))'
3588The incomplete gamma functions reduce to functions such as
3589the exponential integral Ei and the error function for special
3590arguments::
3592 >>> mp.dps = 25
3593 >>> gammainc(0, 4); -ei(-4)
3594 0.00377935240984890647887486
3595 0.00377935240984890647887486
3596 >>> gammainc(0.5, 0, 2); sqrt(pi)*erf(sqrt(2))
3597 1.691806732945198336509541
3598 1.691806732945198336509541
3600"""
3602erf = r"""
3603Computes the error function, `\mathrm{erf}(x)`. The error
3604function is the normalized antiderivative of the Gaussian function
3605`\exp(-t^2)`. More precisely,
3607.. math::
3609 \mathrm{erf}(x) = \frac{2}{\sqrt \pi} \int_0^x \exp(-t^2) \,dt
3611**Basic examples**
3613Simple values and limits include::
3615 >>> from mpmath import *
3616 >>> mp.dps = 15; mp.pretty = True
3617 >>> erf(0)
3618 0.0
3619 >>> erf(1)
3620 0.842700792949715
3621 >>> erf(-1)
3622 -0.842700792949715
3623 >>> erf(inf)
3624 1.0
3625 >>> erf(-inf)
3626 -1.0
3628For large real `x`, `\mathrm{erf}(x)` approaches 1 very
3629rapidly::
3631 >>> erf(3)
3632 0.999977909503001
3633 >>> erf(5)
3634 0.999999999998463
3636The error function is an odd function::
3638 >>> nprint(chop(taylor(erf, 0, 5)))
3639 [0.0, 1.12838, 0.0, -0.376126, 0.0, 0.112838]
3641:func:`~mpmath.erf` implements arbitrary-precision evaluation and
3642supports complex numbers::
3644 >>> mp.dps = 50
3645 >>> erf(0.5)
3646 0.52049987781304653768274665389196452873645157575796
3647 >>> mp.dps = 25
3648 >>> erf(1+j)
3649 (1.316151281697947644880271 + 0.1904534692378346862841089j)
3651Evaluation is supported for large arguments::
3653 >>> mp.dps = 25
3654 >>> erf('1e1000')
3655 1.0
3656 >>> erf('-1e1000')
3657 -1.0
3658 >>> erf('1e-1000')
3659 1.128379167095512573896159e-1000
3660 >>> erf('1e7j')
3661 (0.0 + 8.593897639029319267398803e+43429448190317j)
3662 >>> erf('1e7+1e7j')
3663 (0.9999999858172446172631323 + 3.728805278735270407053139e-8j)
3665**Related functions**
3667See also :func:`~mpmath.erfc`, which is more accurate for large `x`,
3668and :func:`~mpmath.erfi` which gives the antiderivative of
3669`\exp(t^2)`.
3671The Fresnel integrals :func:`~mpmath.fresnels` and :func:`~mpmath.fresnelc`
3672are also related to the error function.
3673"""
3675erfc = r"""
3676Computes the complementary error function,
3677`\mathrm{erfc}(x) = 1-\mathrm{erf}(x)`.
3678This function avoids cancellation that occurs when naively
3679computing the complementary error function as ``1-erf(x)``::
3681 >>> from mpmath import *
3682 >>> mp.dps = 15; mp.pretty = True
3683 >>> 1 - erf(10)
3684 0.0
3685 >>> erfc(10)
3686 2.08848758376254e-45
3688:func:`~mpmath.erfc` works accurately even for ludicrously large
3689arguments::
3691 >>> erfc(10**10)
3692 4.3504398860243e-43429448190325182776
3694Complex arguments are supported::
3696 >>> erfc(500+50j)
3697 (1.19739830969552e-107492 + 1.46072418957528e-107491j)
3699"""
3702erfi = r"""
3703Computes the imaginary error function, `\mathrm{erfi}(x)`.
3704The imaginary error function is defined in analogy with the
3705error function, but with a positive sign in the integrand:
3707.. math ::
3709 \mathrm{erfi}(x) = \frac{2}{\sqrt \pi} \int_0^x \exp(t^2) \,dt
3711Whereas the error function rapidly converges to 1 as `x` grows,
3712the imaginary error function rapidly diverges to infinity.
3713The functions are related as
3714`\mathrm{erfi}(x) = -i\,\mathrm{erf}(ix)` for all complex
3715numbers `x`.
3717**Examples**
3719Basic values and limits::
3721 >>> from mpmath import *
3722 >>> mp.dps = 15; mp.pretty = True
3723 >>> erfi(0)
3724 0.0
3725 >>> erfi(1)
3726 1.65042575879754
3727 >>> erfi(-1)
3728 -1.65042575879754
3729 >>> erfi(inf)
3730 +inf
3731 >>> erfi(-inf)
3732 -inf
3734Note the symmetry between erf and erfi::
3736 >>> erfi(3j)
3737 (0.0 + 0.999977909503001j)
3738 >>> erf(3)
3739 0.999977909503001
3740 >>> erf(1+2j)
3741 (-0.536643565778565 - 5.04914370344703j)
3742 >>> erfi(2+1j)
3743 (-5.04914370344703 - 0.536643565778565j)
3745Large arguments are supported::
3747 >>> erfi(1000)
3748 1.71130938718796e+434291
3749 >>> erfi(10**10)
3750 7.3167287567024e+43429448190325182754
3751 >>> erfi(-10**10)
3752 -7.3167287567024e+43429448190325182754
3753 >>> erfi(1000-500j)
3754 (2.49895233563961e+325717 + 2.6846779342253e+325717j)
3755 >>> erfi(100000j)
3756 (0.0 + 1.0j)
3757 >>> erfi(-100000j)
3758 (0.0 - 1.0j)
3761"""
3763erfinv = r"""
3764Computes the inverse error function, satisfying
3766.. math ::
3768 \mathrm{erf}(\mathrm{erfinv}(x)) =
3769 \mathrm{erfinv}(\mathrm{erf}(x)) = x.
3771This function is defined only for `-1 \le x \le 1`.
3773**Examples**
3775Special values include::
3777 >>> from mpmath import *
3778 >>> mp.dps = 15; mp.pretty = True
3779 >>> erfinv(0)
3780 0.0
3781 >>> erfinv(1)
3782 +inf
3783 >>> erfinv(-1)
3784 -inf
3786The domain is limited to the standard interval::
3788 >>> erfinv(2)
3789 Traceback (most recent call last):
3790 ...
3791 ValueError: erfinv(x) is defined only for -1 <= x <= 1
3793It is simple to check that :func:`~mpmath.erfinv` computes inverse values of
3794:func:`~mpmath.erf` as promised::
3796 >>> erf(erfinv(0.75))
3797 0.75
3798 >>> erf(erfinv(-0.995))
3799 -0.995
3801:func:`~mpmath.erfinv` supports arbitrary-precision evaluation::
3803 >>> mp.dps = 50
3804 >>> x = erf(2)
3805 >>> x
3806 0.99532226501895273416206925636725292861089179704006
3807 >>> erfinv(x)
3808 2.0
3810A definite integral involving the inverse error function::
3812 >>> mp.dps = 15
3813 >>> quad(erfinv, [0, 1])
3814 0.564189583547756
3815 >>> 1/sqrt(pi)
3816 0.564189583547756
3818The inverse error function can be used to generate random numbers
3819with a Gaussian distribution (although this is a relatively
3820inefficient algorithm)::
3822 >>> nprint([erfinv(2*rand()-1) for n in range(6)]) # doctest: +SKIP
3823 [-0.586747, 1.10233, -0.376796, 0.926037, -0.708142, -0.732012]
3825"""
3827npdf = r"""
3828``npdf(x, mu=0, sigma=1)`` evaluates the probability density
3829function of a normal distribution with mean value `\mu`
3830and variance `\sigma^2`.
3832Elementary properties of the probability distribution can
3833be verified using numerical integration::
3835 >>> from mpmath import *
3836 >>> mp.dps = 15; mp.pretty = True
3837 >>> quad(npdf, [-inf, inf])
3838 1.0
3839 >>> quad(lambda x: npdf(x, 3), [3, inf])
3840 0.5
3841 >>> quad(lambda x: npdf(x, 3, 2), [3, inf])
3842 0.5
3844See also :func:`~mpmath.ncdf`, which gives the cumulative
3845distribution.
3846"""
3848ncdf = r"""
3849``ncdf(x, mu=0, sigma=1)`` evaluates the cumulative distribution
3850function of a normal distribution with mean value `\mu`
3851and variance `\sigma^2`.
3853See also :func:`~mpmath.npdf`, which gives the probability density.
3855Elementary properties include::
3857 >>> from mpmath import *
3858 >>> mp.dps = 15; mp.pretty = True
3859 >>> ncdf(pi, mu=pi)
3860 0.5
3861 >>> ncdf(-inf)
3862 0.0
3863 >>> ncdf(+inf)
3864 1.0
3866The cumulative distribution is the integral of the density
3867function having identical mu and sigma::
3869 >>> mp.dps = 15
3870 >>> diff(ncdf, 2)
3871 0.053990966513188
3872 >>> npdf(2)
3873 0.053990966513188
3874 >>> diff(lambda x: ncdf(x, 1, 0.5), 0)
3875 0.107981933026376
3876 >>> npdf(0, 1, 0.5)
3877 0.107981933026376
3878"""
3880expint = r"""
3881:func:`~mpmath.expint(n,z)` gives the generalized exponential integral
3882or En-function,
3884.. math ::
3886 \mathrm{E}_n(z) = \int_1^{\infty} \frac{e^{-zt}}{t^n} dt,
3888where `n` and `z` may both be complex numbers. The case with `n = 1` is
3889also given by :func:`~mpmath.e1`.
3891**Examples**
3893Evaluation at real and complex arguments::
3895 >>> from mpmath import *
3896 >>> mp.dps = 25; mp.pretty = True
3897 >>> expint(1, 6.25)
3898 0.0002704758872637179088496194
3899 >>> expint(-3, 2+3j)
3900 (0.00299658467335472929656159 + 0.06100816202125885450319632j)
3901 >>> expint(2+3j, 4-5j)
3902 (0.001803529474663565056945248 - 0.002235061547756185403349091j)
3904At negative integer values of `n`, `E_n(z)` reduces to a
3905rational-exponential function::
3907 >>> f = lambda n, z: fac(n)*sum(z**k/fac(k-1) for k in range(1,n+2))/\
3908 ... exp(z)/z**(n+2)
3909 >>> n = 3
3910 >>> z = 1/pi
3911 >>> expint(-n,z)
3912 584.2604820613019908668219
3913 >>> f(n,z)
3914 584.2604820613019908668219
3915 >>> n = 5
3916 >>> expint(-n,z)
3917 115366.5762594725451811138
3918 >>> f(n,z)
3919 115366.5762594725451811138
3920"""
3922e1 = r"""
3923Computes the exponential integral `\mathrm{E}_1(z)`, given by
3925.. math ::
3927 \mathrm{E}_1(z) = \int_z^{\infty} \frac{e^{-t}}{t} dt.
3929This is equivalent to :func:`~mpmath.expint` with `n = 1`.
3931**Examples**
3933Two ways to evaluate this function::
3935 >>> from mpmath import *
3936 >>> mp.dps = 25; mp.pretty = True
3937 >>> e1(6.25)
3938 0.0002704758872637179088496194
3939 >>> expint(1,6.25)
3940 0.0002704758872637179088496194
3942The E1-function is essentially the same as the Ei-function (:func:`~mpmath.ei`)
3943with negated argument, except for an imaginary branch cut term::
3945 >>> e1(2.5)
3946 0.02491491787026973549562801
3947 >>> -ei(-2.5)
3948 0.02491491787026973549562801
3949 >>> e1(-2.5)
3950 (-7.073765894578600711923552 - 3.141592653589793238462643j)
3951 >>> -ei(2.5)
3952 -7.073765894578600711923552
3954"""
3956ei = r"""
3957Computes the exponential integral or Ei-function, `\mathrm{Ei}(x)`.
3958The exponential integral is defined as
3960.. math ::
3962 \mathrm{Ei}(x) = \int_{-\infty\,}^x \frac{e^t}{t} \, dt.
3964When the integration range includes `t = 0`, the exponential
3965integral is interpreted as providing the Cauchy principal value.
3967For real `x`, the Ei-function behaves roughly like
3968`\mathrm{Ei}(x) \approx \exp(x) + \log(|x|)`.
3970The Ei-function is related to the more general family of exponential
3971integral functions denoted by `E_n`, which are available as :func:`~mpmath.expint`.
3973**Basic examples**
3975Some basic values and limits are::
3977 >>> from mpmath import *
3978 >>> mp.dps = 15; mp.pretty = True
3979 >>> ei(0)
3980 -inf
3981 >>> ei(1)
3982 1.89511781635594
3983 >>> ei(inf)
3984 +inf
3985 >>> ei(-inf)
3986 0.0
3988For `x < 0`, the defining integral can be evaluated
3989numerically as a reference::
3991 >>> ei(-4)
3992 -0.00377935240984891
3993 >>> quad(lambda t: exp(t)/t, [-inf, -4])
3994 -0.00377935240984891
3996:func:`~mpmath.ei` supports complex arguments and arbitrary
3997precision evaluation::
3999 >>> mp.dps = 50
4000 >>> ei(pi)
4001 10.928374389331410348638445906907535171566338835056
4002 >>> mp.dps = 25
4003 >>> ei(3+4j)
4004 (-4.154091651642689822535359 + 4.294418620024357476985535j)
4006**Related functions**
4008The exponential integral is closely related to the logarithmic
4009integral. See :func:`~mpmath.li` for additional information.
4011The exponential integral is related to the hyperbolic
4012and trigonometric integrals (see :func:`~mpmath.chi`, :func:`~mpmath.shi`,
4013:func:`~mpmath.ci`, :func:`~mpmath.si`) similarly to how the ordinary
4014exponential function is related to the hyperbolic and
4015trigonometric functions::
4017 >>> mp.dps = 15
4018 >>> ei(3)
4019 9.93383257062542
4020 >>> chi(3) + shi(3)
4021 9.93383257062542
4022 >>> chop(ci(3j) - j*si(3j) - pi*j/2)
4023 9.93383257062542
4025Beware that logarithmic corrections, as in the last example
4026above, are required to obtain the correct branch in general.
4027For details, see [1].
4029The exponential integral is also a special case of the
4030hypergeometric function `\,_2F_2`::
4032 >>> z = 0.6
4033 >>> z*hyper([1,1],[2,2],z) + (ln(z)-ln(1/z))/2 + euler
4034 0.769881289937359
4035 >>> ei(z)
4036 0.769881289937359
4038**References**
40401. Relations between Ei and other functions:
4041 http://functions.wolfram.com/GammaBetaErf/ExpIntegralEi/27/01/
40432. Abramowitz & Stegun, section 5:
4044 http://people.math.sfu.ca/~cbm/aands/page_228.htm
40463. Asymptotic expansion for Ei:
4047 http://mathworld.wolfram.com/En-Function.html
4048"""
4050li = r"""
4051Computes the logarithmic integral or li-function
4052`\mathrm{li}(x)`, defined by
4054.. math ::
4056 \mathrm{li}(x) = \int_0^x \frac{1}{\log t} \, dt
4058The logarithmic integral has a singularity at `x = 1`.
4060Alternatively, ``li(x, offset=True)`` computes the offset
4061logarithmic integral (used in number theory)
4063.. math ::
4065 \mathrm{Li}(x) = \int_2^x \frac{1}{\log t} \, dt.
4067These two functions are related via the simple identity
4068`\mathrm{Li}(x) = \mathrm{li}(x) - \mathrm{li}(2)`.
4070The logarithmic integral should also not be confused with
4071the polylogarithm (also denoted by Li), which is implemented
4072as :func:`~mpmath.polylog`.
4074**Examples**
4076Some basic values and limits::
4078 >>> from mpmath import *
4079 >>> mp.dps = 30; mp.pretty = True
4080 >>> li(0)
4081 0.0
4082 >>> li(1)
4083 -inf
4084 >>> li(1)
4085 -inf
4086 >>> li(2)
4087 1.04516378011749278484458888919
4088 >>> findroot(li, 2)
4089 1.45136923488338105028396848589
4090 >>> li(inf)
4091 +inf
4092 >>> li(2, offset=True)
4093 0.0
4094 >>> li(1, offset=True)
4095 -inf
4096 >>> li(0, offset=True)
4097 -1.04516378011749278484458888919
4098 >>> li(10, offset=True)
4099 5.12043572466980515267839286347
4101The logarithmic integral can be evaluated for arbitrary
4102complex arguments::
4104 >>> mp.dps = 20
4105 >>> li(3+4j)
4106 (3.1343755504645775265 + 2.6769247817778742392j)
4108The logarithmic integral is related to the exponential integral::
4110 >>> ei(log(3))
4111 2.1635885946671919729
4112 >>> li(3)
4113 2.1635885946671919729
4115The logarithmic integral grows like `O(x/\log(x))`::
4117 >>> mp.dps = 15
4118 >>> x = 10**100
4119 >>> x/log(x)
4120 4.34294481903252e+97
4121 >>> li(x)
4122 4.3619719871407e+97
4124The prime number theorem states that the number of primes less
4125than `x` is asymptotic to `\mathrm{Li}(x)` (equivalently
4126`\mathrm{li}(x)`). For example, it is known that there are
4127exactly 1,925,320,391,606,803,968,923 prime numbers less than
4128`10^{23}` [1]. The logarithmic integral provides a very
4129accurate estimate::
4131 >>> li(10**23, offset=True)
4132 1.92532039161405e+21
4134A definite integral is::
4136 >>> quad(li, [0, 1])
4137 -0.693147180559945
4138 >>> -ln(2)
4139 -0.693147180559945
4141**References**
41431. http://mathworld.wolfram.com/PrimeCountingFunction.html
41452. http://mathworld.wolfram.com/LogarithmicIntegral.html
4147"""
4149ci = r"""
4150Computes the cosine integral,
4152.. math ::
4154 \mathrm{Ci}(x) = -\int_x^{\infty} \frac{\cos t}{t}\,dt
4155 = \gamma + \log x + \int_0^x \frac{\cos t - 1}{t}\,dt
4157**Examples**
4159Some values and limits::
4161 >>> from mpmath import *
4162 >>> mp.dps = 25; mp.pretty = True
4163 >>> ci(0)
4164 -inf
4165 >>> ci(1)
4166 0.3374039229009681346626462
4167 >>> ci(pi)
4168 0.07366791204642548599010096
4169 >>> ci(inf)
4170 0.0
4171 >>> ci(-inf)
4172 (0.0 + 3.141592653589793238462643j)
4173 >>> ci(2+3j)
4174 (1.408292501520849518759125 - 2.983617742029605093121118j)
4176The cosine integral behaves roughly like the sinc function
4177(see :func:`~mpmath.sinc`) for large real `x`::
4179 >>> ci(10**10)
4180 -4.875060251748226537857298e-11
4181 >>> sinc(10**10)
4182 -4.875060250875106915277943e-11
4183 >>> chop(limit(ci, inf))
4184 0.0
4186It has infinitely many roots on the positive real axis::
4188 >>> findroot(ci, 1)
4189 0.6165054856207162337971104
4190 >>> findroot(ci, 2)
4191 3.384180422551186426397851
4193Evaluation is supported for `z` anywhere in the complex plane::
4195 >>> ci(10**6*(1+j))
4196 (4.449410587611035724984376e+434287 + 9.75744874290013526417059e+434287j)
4198We can evaluate the defining integral as a reference::
4200 >>> mp.dps = 15
4201 >>> -quadosc(lambda t: cos(t)/t, [5, inf], omega=1)
4202 -0.190029749656644
4203 >>> ci(5)
4204 -0.190029749656644
4206Some infinite series can be evaluated using the
4207cosine integral::
4209 >>> nsum(lambda k: (-1)**k/(fac(2*k)*(2*k)), [1,inf])
4210 -0.239811742000565
4211 >>> ci(1) - euler
4212 -0.239811742000565
4214"""
4216si = r"""
4217Computes the sine integral,
4219.. math ::
4221 \mathrm{Si}(x) = \int_0^x \frac{\sin t}{t}\,dt.
4223The sine integral is thus the antiderivative of the sinc
4224function (see :func:`~mpmath.sinc`).
4226**Examples**
4228Some values and limits::
4230 >>> from mpmath import *
4231 >>> mp.dps = 25; mp.pretty = True
4232 >>> si(0)
4233 0.0
4234 >>> si(1)
4235 0.9460830703671830149413533
4236 >>> si(-1)
4237 -0.9460830703671830149413533
4238 >>> si(pi)
4239 1.851937051982466170361053
4240 >>> si(inf)
4241 1.570796326794896619231322
4242 >>> si(-inf)
4243 -1.570796326794896619231322
4244 >>> si(2+3j)
4245 (4.547513889562289219853204 + 1.399196580646054789459839j)
4247The sine integral approaches `\pi/2` for large real `x`::
4249 >>> si(10**10)
4250 1.570796326707584656968511
4251 >>> pi/2
4252 1.570796326794896619231322
4254Evaluation is supported for `z` anywhere in the complex plane::
4256 >>> si(10**6*(1+j))
4257 (-9.75744874290013526417059e+434287 + 4.449410587611035724984376e+434287j)
4259We can evaluate the defining integral as a reference::
4261 >>> mp.dps = 15
4262 >>> quad(sinc, [0, 5])
4263 1.54993124494467
4264 >>> si(5)
4265 1.54993124494467
4267Some infinite series can be evaluated using the
4268sine integral::
4270 >>> nsum(lambda k: (-1)**k/(fac(2*k+1)*(2*k+1)), [0,inf])
4271 0.946083070367183
4272 >>> si(1)
4273 0.946083070367183
4275"""
4277chi = r"""
4278Computes the hyperbolic cosine integral, defined
4279in analogy with the cosine integral (see :func:`~mpmath.ci`) as
4281.. math ::
4283 \mathrm{Chi}(x) = -\int_x^{\infty} \frac{\cosh t}{t}\,dt
4284 = \gamma + \log x + \int_0^x \frac{\cosh t - 1}{t}\,dt
4286Some values and limits::
4288 >>> from mpmath import *
4289 >>> mp.dps = 25; mp.pretty = True
4290 >>> chi(0)
4291 -inf
4292 >>> chi(1)
4293 0.8378669409802082408946786
4294 >>> chi(inf)
4295 +inf
4296 >>> findroot(chi, 0.5)
4297 0.5238225713898644064509583
4298 >>> chi(2+3j)
4299 (-0.1683628683277204662429321 + 2.625115880451325002151688j)
4301Evaluation is supported for `z` anywhere in the complex plane::
4303 >>> chi(10**6*(1+j))
4304 (4.449410587611035724984376e+434287 - 9.75744874290013526417059e+434287j)
4306"""
4308shi = r"""
4309Computes the hyperbolic sine integral, defined
4310in analogy with the sine integral (see :func:`~mpmath.si`) as
4312.. math ::
4314 \mathrm{Shi}(x) = \int_0^x \frac{\sinh t}{t}\,dt.
4316Some values and limits::
4318 >>> from mpmath import *
4319 >>> mp.dps = 25; mp.pretty = True
4320 >>> shi(0)
4321 0.0
4322 >>> shi(1)
4323 1.057250875375728514571842
4324 >>> shi(-1)
4325 -1.057250875375728514571842
4326 >>> shi(inf)
4327 +inf
4328 >>> shi(2+3j)
4329 (-0.1931890762719198291678095 + 2.645432555362369624818525j)
4331Evaluation is supported for `z` anywhere in the complex plane::
4333 >>> shi(10**6*(1+j))
4334 (4.449410587611035724984376e+434287 - 9.75744874290013526417059e+434287j)
4336"""
4338fresnels = r"""
4339Computes the Fresnel sine integral
4341.. math ::
4343 S(x) = \int_0^x \sin\left(\frac{\pi t^2}{2}\right) \,dt
4345Note that some sources define this function
4346without the normalization factor `\pi/2`.
4348**Examples**
4350Some basic values and limits::
4352 >>> from mpmath import *
4353 >>> mp.dps = 25; mp.pretty = True
4354 >>> fresnels(0)
4355 0.0
4356 >>> fresnels(inf)
4357 0.5
4358 >>> fresnels(-inf)
4359 -0.5
4360 >>> fresnels(1)
4361 0.4382591473903547660767567
4362 >>> fresnels(1+2j)
4363 (36.72546488399143842838788 + 15.58775110440458732748279j)
4365Comparing with the definition::
4367 >>> fresnels(3)
4368 0.4963129989673750360976123
4369 >>> quad(lambda t: sin(pi*t**2/2), [0,3])
4370 0.4963129989673750360976123
4371"""
4373fresnelc = r"""
4374Computes the Fresnel cosine integral
4376.. math ::
4378 C(x) = \int_0^x \cos\left(\frac{\pi t^2}{2}\right) \,dt
4380Note that some sources define this function
4381without the normalization factor `\pi/2`.
4383**Examples**
4385Some basic values and limits::
4387 >>> from mpmath import *
4388 >>> mp.dps = 25; mp.pretty = True
4389 >>> fresnelc(0)
4390 0.0
4391 >>> fresnelc(inf)
4392 0.5
4393 >>> fresnelc(-inf)
4394 -0.5
4395 >>> fresnelc(1)
4396 0.7798934003768228294742064
4397 >>> fresnelc(1+2j)
4398 (16.08787137412548041729489 - 36.22568799288165021578758j)
4400Comparing with the definition::
4402 >>> fresnelc(3)
4403 0.6057207892976856295561611
4404 >>> quad(lambda t: cos(pi*t**2/2), [0,3])
4405 0.6057207892976856295561611
4406"""
4408airyai = r"""
4409Computes the Airy function `\operatorname{Ai}(z)`, which is
4410the solution of the Airy differential equation `f''(z) - z f(z) = 0`
4411with initial conditions
4413.. math ::
4415 \operatorname{Ai}(0) =
4416 \frac{1}{3^{2/3}\Gamma\left(\frac{2}{3}\right)}
4418 \operatorname{Ai}'(0) =
4419 -\frac{1}{3^{1/3}\Gamma\left(\frac{1}{3}\right)}.
4421Other common ways of defining the Ai-function include
4422integrals such as
4424.. math ::
4426 \operatorname{Ai}(x) = \frac{1}{\pi}
4427 \int_0^{\infty} \cos\left(\frac{1}{3}t^3+xt\right) dt
4428 \qquad x \in \mathbb{R}
4430 \operatorname{Ai}(z) = \frac{\sqrt{3}}{2\pi}
4431 \int_0^{\infty}
4432 \exp\left(-\frac{t^3}{3}-\frac{z^3}{3t^3}\right) dt.
4434The Ai-function is an entire function with a turning point,
4435behaving roughly like a slowly decaying sine wave for `z < 0` and
4436like a rapidly decreasing exponential for `z > 0`.
4437A second solution of the Airy differential equation
4438is given by `\operatorname{Bi}(z)` (see :func:`~mpmath.airybi`).
4440Optionally, with *derivative=alpha*, :func:`airyai` can compute the
4441`\alpha`-th order fractional derivative with respect to `z`.
4442For `\alpha = n = 1,2,3,\ldots` this gives the derivative
4443`\operatorname{Ai}^{(n)}(z)`, and for `\alpha = -n = -1,-2,-3,\ldots`
4444this gives the `n`-fold iterated integral
4446.. math ::
4448 f_0(z) = \operatorname{Ai}(z)
4450 f_n(z) = \int_0^z f_{n-1}(t) dt.
4452The Ai-function has infinitely many zeros, all located along the
4453negative half of the real axis. They can be computed with
4454:func:`~mpmath.airyaizero`.
4456**Plots**
4458.. literalinclude :: /plots/ai.py
4459.. image :: /plots/ai.png
4460.. literalinclude :: /plots/ai_c.py
4461.. image :: /plots/ai_c.png
4463**Basic examples**
4465Limits and values include::
4467 >>> from mpmath import *
4468 >>> mp.dps = 25; mp.pretty = True
4469 >>> airyai(0); 1/(power(3,'2/3')*gamma('2/3'))
4470 0.3550280538878172392600632
4471 0.3550280538878172392600632
4472 >>> airyai(1)
4473 0.1352924163128814155241474
4474 >>> airyai(-1)
4475 0.5355608832923521187995166
4476 >>> airyai(inf); airyai(-inf)
4477 0.0
4478 0.0
4480Evaluation is supported for large magnitudes of the argument::
4482 >>> airyai(-100)
4483 0.1767533932395528780908311
4484 >>> airyai(100)
4485 2.634482152088184489550553e-291
4486 >>> airyai(50+50j)
4487 (-5.31790195707456404099817e-68 - 1.163588003770709748720107e-67j)
4488 >>> airyai(-50+50j)
4489 (1.041242537363167632587245e+158 + 3.347525544923600321838281e+157j)
4491Huge arguments are also fine::
4493 >>> airyai(10**10)
4494 1.162235978298741779953693e-289529654602171
4495 >>> airyai(-10**10)
4496 0.0001736206448152818510510181
4497 >>> w = airyai(10**10*(1+j))
4498 >>> w.real
4499 5.711508683721355528322567e-186339621747698
4500 >>> w.imag
4501 1.867245506962312577848166e-186339621747697
4503The first root of the Ai-function is::
4505 >>> findroot(airyai, -2)
4506 -2.338107410459767038489197
4507 >>> airyaizero(1)
4508 -2.338107410459767038489197
4510**Properties and relations**
4512Verifying the Airy differential equation::
4514 >>> for z in [-3.4, 0, 2.5, 1+2j]:
4515 ... chop(airyai(z,2) - z*airyai(z))
4516 ...
4517 0.0
4518 0.0
4519 0.0
4520 0.0
4522The first few terms of the Taylor series expansion around `z = 0`
4523(every third term is zero)::
4525 >>> nprint(taylor(airyai, 0, 5))
4526 [0.355028, -0.258819, 0.0, 0.0591713, -0.0215683, 0.0]
4528The Airy functions satisfy the Wronskian relation
4529`\operatorname{Ai}(z) \operatorname{Bi}'(z) -
4530\operatorname{Ai}'(z) \operatorname{Bi}(z) = 1/\pi`::
4532 >>> z = -0.5
4533 >>> airyai(z)*airybi(z,1) - airyai(z,1)*airybi(z)
4534 0.3183098861837906715377675
4535 >>> 1/pi
4536 0.3183098861837906715377675
4538The Airy functions can be expressed in terms of Bessel
4539functions of order `\pm 1/3`. For `\Re[z] \le 0`, we have::
4541 >>> z = -3
4542 >>> airyai(z)
4543 -0.3788142936776580743472439
4544 >>> y = 2*power(-z,'3/2')/3
4545 >>> (sqrt(-z) * (besselj('1/3',y) + besselj('-1/3',y)))/3
4546 -0.3788142936776580743472439
4548**Derivatives and integrals**
4550Derivatives of the Ai-function (directly and using :func:`~mpmath.diff`)::
4552 >>> airyai(-3,1); diff(airyai,-3)
4553 0.3145837692165988136507873
4554 0.3145837692165988136507873
4555 >>> airyai(-3,2); diff(airyai,-3,2)
4556 1.136442881032974223041732
4557 1.136442881032974223041732
4558 >>> airyai(1000,1); diff(airyai,1000)
4559 -2.943133917910336090459748e-9156
4560 -2.943133917910336090459748e-9156
4562Several derivatives at `z = 0`::
4564 >>> airyai(0,0); airyai(0,1); airyai(0,2)
4565 0.3550280538878172392600632
4566 -0.2588194037928067984051836
4567 0.0
4568 >>> airyai(0,3); airyai(0,4); airyai(0,5)
4569 0.3550280538878172392600632
4570 -0.5176388075856135968103671
4571 0.0
4572 >>> airyai(0,15); airyai(0,16); airyai(0,17)
4573 1292.30211615165475090663
4574 -3188.655054727379756351861
4575 0.0
4577The integral of the Ai-function::
4579 >>> airyai(3,-1); quad(airyai, [0,3])
4580 0.3299203760070217725002701
4581 0.3299203760070217725002701
4582 >>> airyai(-10,-1); quad(airyai, [0,-10])
4583 -0.765698403134212917425148
4584 -0.765698403134212917425148
4586Integrals of high or fractional order::
4588 >>> airyai(-2,0.5); differint(airyai,-2,0.5,0)
4589 (0.0 + 0.2453596101351438273844725j)
4590 (0.0 + 0.2453596101351438273844725j)
4591 >>> airyai(-2,-4); differint(airyai,-2,-4,0)
4592 0.2939176441636809580339365
4593 0.2939176441636809580339365
4594 >>> airyai(0,-1); airyai(0,-2); airyai(0,-3)
4595 0.0
4596 0.0
4597 0.0
4599Integrals of the Ai-function can be evaluated at limit points::
4601 >>> airyai(-1000000,-1); airyai(-inf,-1)
4602 -0.6666843728311539978751512
4603 -0.6666666666666666666666667
4604 >>> airyai(10,-1); airyai(+inf,-1)
4605 0.3333333332991690159427932
4606 0.3333333333333333333333333
4607 >>> airyai(+inf,-2); airyai(+inf,-3)
4608 +inf
4609 +inf
4610 >>> airyai(-1000000,-2); airyai(-inf,-2)
4611 666666.4078472650651209742
4612 +inf
4613 >>> airyai(-1000000,-3); airyai(-inf,-3)
4614 -333333074513.7520264995733
4615 -inf
4617**References**
46191. [DLMF]_ Chapter 9: Airy and Related Functions
46202. [WolframFunctions]_ section: Bessel-Type Functions
4622"""
4624airybi = r"""
4625Computes the Airy function `\operatorname{Bi}(z)`, which is
4626the solution of the Airy differential equation `f''(z) - z f(z) = 0`
4627with initial conditions
4629.. math ::
4631 \operatorname{Bi}(0) =
4632 \frac{1}{3^{1/6}\Gamma\left(\frac{2}{3}\right)}
4634 \operatorname{Bi}'(0) =
4635 \frac{3^{1/6}}{\Gamma\left(\frac{1}{3}\right)}.
4637Like the Ai-function (see :func:`~mpmath.airyai`), the Bi-function
4638is oscillatory for `z < 0`, but it grows rather than decreases
4639for `z > 0`.
4641Optionally, as for :func:`~mpmath.airyai`, derivatives, integrals
4642and fractional derivatives can be computed with the *derivative*
4643parameter.
4645The Bi-function has infinitely many zeros along the negative
4646half-axis, as well as complex zeros, which can all be computed
4647with :func:`~mpmath.airybizero`.
4649**Plots**
4651.. literalinclude :: /plots/bi.py
4652.. image :: /plots/bi.png
4653.. literalinclude :: /plots/bi_c.py
4654.. image :: /plots/bi_c.png
4656**Basic examples**
4658Limits and values include::
4660 >>> from mpmath import *
4661 >>> mp.dps = 25; mp.pretty = True
4662 >>> airybi(0); 1/(power(3,'1/6')*gamma('2/3'))
4663 0.6149266274460007351509224
4664 0.6149266274460007351509224
4665 >>> airybi(1)
4666 1.207423594952871259436379
4667 >>> airybi(-1)
4668 0.10399738949694461188869
4669 >>> airybi(inf); airybi(-inf)
4670 +inf
4671 0.0
4673Evaluation is supported for large magnitudes of the argument::
4675 >>> airybi(-100)
4676 0.02427388768016013160566747
4677 >>> airybi(100)
4678 6.041223996670201399005265e+288
4679 >>> airybi(50+50j)
4680 (-5.322076267321435669290334e+63 + 1.478450291165243789749427e+65j)
4681 >>> airybi(-50+50j)
4682 (-3.347525544923600321838281e+157 + 1.041242537363167632587245e+158j)
4684Huge arguments::
4686 >>> airybi(10**10)
4687 1.369385787943539818688433e+289529654602165
4688 >>> airybi(-10**10)
4689 0.001775656141692932747610973
4690 >>> w = airybi(10**10*(1+j))
4691 >>> w.real
4692 -6.559955931096196875845858e+186339621747689
4693 >>> w.imag
4694 -6.822462726981357180929024e+186339621747690
4696The first real root of the Bi-function is::
4698 >>> findroot(airybi, -1); airybizero(1)
4699 -1.17371322270912792491998
4700 -1.17371322270912792491998
4702**Properties and relations**
4704Verifying the Airy differential equation::
4706 >>> for z in [-3.4, 0, 2.5, 1+2j]:
4707 ... chop(airybi(z,2) - z*airybi(z))
4708 ...
4709 0.0
4710 0.0
4711 0.0
4712 0.0
4714The first few terms of the Taylor series expansion around `z = 0`
4715(every third term is zero)::
4717 >>> nprint(taylor(airybi, 0, 5))
4718 [0.614927, 0.448288, 0.0, 0.102488, 0.0373574, 0.0]
4720The Airy functions can be expressed in terms of Bessel
4721functions of order `\pm 1/3`. For `\Re[z] \le 0`, we have::
4723 >>> z = -3
4724 >>> airybi(z)
4725 -0.1982896263749265432206449
4726 >>> p = 2*power(-z,'3/2')/3
4727 >>> sqrt(-mpf(z)/3)*(besselj('-1/3',p) - besselj('1/3',p))
4728 -0.1982896263749265432206449
4730**Derivatives and integrals**
4732Derivatives of the Bi-function (directly and using :func:`~mpmath.diff`)::
4734 >>> airybi(-3,1); diff(airybi,-3)
4735 -0.675611222685258537668032
4736 -0.675611222685258537668032
4737 >>> airybi(-3,2); diff(airybi,-3,2)
4738 0.5948688791247796296619346
4739 0.5948688791247796296619346
4740 >>> airybi(1000,1); diff(airybi,1000)
4741 1.710055114624614989262335e+9156
4742 1.710055114624614989262335e+9156
4744Several derivatives at `z = 0`::
4746 >>> airybi(0,0); airybi(0,1); airybi(0,2)
4747 0.6149266274460007351509224
4748 0.4482883573538263579148237
4749 0.0
4750 >>> airybi(0,3); airybi(0,4); airybi(0,5)
4751 0.6149266274460007351509224
4752 0.8965767147076527158296474
4753 0.0
4754 >>> airybi(0,15); airybi(0,16); airybi(0,17)
4755 2238.332923903442675949357
4756 5522.912562599140729510628
4757 0.0
4759The integral of the Bi-function::
4761 >>> airybi(3,-1); quad(airybi, [0,3])
4762 10.06200303130620056316655
4763 10.06200303130620056316655
4764 >>> airybi(-10,-1); quad(airybi, [0,-10])
4765 -0.01504042480614002045135483
4766 -0.01504042480614002045135483
4768Integrals of high or fractional order::
4770 >>> airybi(-2,0.5); differint(airybi, -2, 0.5, 0)
4771 (0.0 + 0.5019859055341699223453257j)
4772 (0.0 + 0.5019859055341699223453257j)
4773 >>> airybi(-2,-4); differint(airybi,-2,-4,0)
4774 0.2809314599922447252139092
4775 0.2809314599922447252139092
4776 >>> airybi(0,-1); airybi(0,-2); airybi(0,-3)
4777 0.0
4778 0.0
4779 0.0
4781Integrals of the Bi-function can be evaluated at limit points::
4783 >>> airybi(-1000000,-1); airybi(-inf,-1)
4784 0.000002191261128063434047966873
4785 0.0
4786 >>> airybi(10,-1); airybi(+inf,-1)
4787 147809803.1074067161675853
4788 +inf
4789 >>> airybi(+inf,-2); airybi(+inf,-3)
4790 +inf
4791 +inf
4792 >>> airybi(-1000000,-2); airybi(-inf,-2)
4793 0.4482883750599908479851085
4794 0.4482883573538263579148237
4795 >>> gamma('2/3')*power(3,'2/3')/(2*pi)
4796 0.4482883573538263579148237
4797 >>> airybi(-100000,-3); airybi(-inf,-3)
4798 -44828.52827206932872493133
4799 -inf
4800 >>> airybi(-100000,-4); airybi(-inf,-4)
4801 2241411040.437759489540248
4802 +inf
4804"""
4806airyaizero = r"""
4807Gives the `k`-th zero of the Airy Ai-function,
4808i.e. the `k`-th number `a_k` ordered by magnitude for which
4809`\operatorname{Ai}(a_k) = 0`.
4811Optionally, with *derivative=1*, the corresponding
4812zero `a'_k` of the derivative function, i.e.
4813`\operatorname{Ai}'(a'_k) = 0`, is computed.
4815**Examples**
4817Some values of `a_k`::
4819 >>> from mpmath import *
4820 >>> mp.dps = 25; mp.pretty = True
4821 >>> airyaizero(1)
4822 -2.338107410459767038489197
4823 >>> airyaizero(2)
4824 -4.087949444130970616636989
4825 >>> airyaizero(3)
4826 -5.520559828095551059129856
4827 >>> airyaizero(1000)
4828 -281.0315196125215528353364
4830Some values of `a'_k`::
4832 >>> airyaizero(1,1)
4833 -1.018792971647471089017325
4834 >>> airyaizero(2,1)
4835 -3.248197582179836537875424
4836 >>> airyaizero(3,1)
4837 -4.820099211178735639400616
4838 >>> airyaizero(1000,1)
4839 -280.9378080358935070607097
4841Verification::
4843 >>> chop(airyai(airyaizero(1)))
4844 0.0
4845 >>> chop(airyai(airyaizero(1,1),1))
4846 0.0
4848"""
4850airybizero = r"""
4851With *complex=False*, gives the `k`-th real zero of the Airy Bi-function,
4852i.e. the `k`-th number `b_k` ordered by magnitude for which
4853`\operatorname{Bi}(b_k) = 0`.
4855With *complex=True*, gives the `k`-th complex zero in the upper
4856half plane `\beta_k`. Also the conjugate `\overline{\beta_k}`
4857is a zero.
4859Optionally, with *derivative=1*, the corresponding
4860zero `b'_k` or `\beta'_k` of the derivative function, i.e.
4861`\operatorname{Bi}'(b'_k) = 0` or `\operatorname{Bi}'(\beta'_k) = 0`,
4862is computed.
4864**Examples**
4866Some values of `b_k`::
4868 >>> from mpmath import *
4869 >>> mp.dps = 25; mp.pretty = True
4870 >>> airybizero(1)
4871 -1.17371322270912792491998
4872 >>> airybizero(2)
4873 -3.271093302836352715680228
4874 >>> airybizero(3)
4875 -4.830737841662015932667709
4876 >>> airybizero(1000)
4877 -280.9378112034152401578834
4879Some values of `b_k`::
4881 >>> airybizero(1,1)
4882 -2.294439682614123246622459
4883 >>> airybizero(2,1)
4884 -4.073155089071828215552369
4885 >>> airybizero(3,1)
4886 -5.512395729663599496259593
4887 >>> airybizero(1000,1)
4888 -281.0315164471118527161362
4890Some values of `\beta_k`::
4892 >>> airybizero(1,complex=True)
4893 (0.9775448867316206859469927 + 2.141290706038744575749139j)
4894 >>> airybizero(2,complex=True)
4895 (1.896775013895336346627217 + 3.627291764358919410440499j)
4896 >>> airybizero(3,complex=True)
4897 (2.633157739354946595708019 + 4.855468179979844983174628j)
4898 >>> airybizero(1000,complex=True)
4899 (140.4978560578493018899793 + 243.3907724215792121244867j)
4901Some values of `\beta'_k`::
4903 >>> airybizero(1,1,complex=True)
4904 (0.2149470745374305676088329 + 1.100600143302797880647194j)
4905 >>> airybizero(2,1,complex=True)
4906 (1.458168309223507392028211 + 2.912249367458445419235083j)
4907 >>> airybizero(3,1,complex=True)
4908 (2.273760763013482299792362 + 4.254528549217097862167015j)
4909 >>> airybizero(1000,1,complex=True)
4910 (140.4509972835270559730423 + 243.3096175398562811896208j)
4912Verification::
4914 >>> chop(airybi(airybizero(1)))
4915 0.0
4916 >>> chop(airybi(airybizero(1,1),1))
4917 0.0
4918 >>> u = airybizero(1,complex=True)
4919 >>> chop(airybi(u))
4920 0.0
4921 >>> chop(airybi(conj(u)))
4922 0.0
4924The complex zeros (in the upper and lower half-planes respectively)
4925asymptotically approach the rays `z = R \exp(\pm i \pi /3)`::
4927 >>> arg(airybizero(1,complex=True))
4928 1.142532510286334022305364
4929 >>> arg(airybizero(1000,complex=True))
4930 1.047271114786212061583917
4931 >>> arg(airybizero(1000000,complex=True))
4932 1.047197624741816183341355
4933 >>> pi/3
4934 1.047197551196597746154214
4936"""
4939ellipk = r"""
4940Evaluates the complete elliptic integral of the first kind,
4941`K(m)`, defined by
4943.. math ::
4945 K(m) = \int_0^{\pi/2} \frac{dt}{\sqrt{1-m \sin^2 t}} \, = \,
4946 \frac{\pi}{2} \,_2F_1\left(\frac{1}{2}, \frac{1}{2}, 1, m\right).
4948Note that the argument is the parameter `m = k^2`,
4949not the modulus `k` which is sometimes used.
4951**Plots**
4953.. literalinclude :: /plots/ellipk.py
4954.. image :: /plots/ellipk.png
4956**Examples**
4958Values and limits include::
4960 >>> from mpmath import *
4961 >>> mp.dps = 25; mp.pretty = True
4962 >>> ellipk(0)
4963 1.570796326794896619231322
4964 >>> ellipk(inf)
4965 (0.0 + 0.0j)
4966 >>> ellipk(-inf)
4967 0.0
4968 >>> ellipk(1)
4969 +inf
4970 >>> ellipk(-1)
4971 1.31102877714605990523242
4972 >>> ellipk(2)
4973 (1.31102877714605990523242 - 1.31102877714605990523242j)
4975Verifying the defining integral and hypergeometric
4976representation::
4978 >>> ellipk(0.5)
4979 1.85407467730137191843385
4980 >>> quad(lambda t: (1-0.5*sin(t)**2)**-0.5, [0, pi/2])
4981 1.85407467730137191843385
4982 >>> pi/2*hyp2f1(0.5,0.5,1,0.5)
4983 1.85407467730137191843385
4985Evaluation is supported for arbitrary complex `m`::
4987 >>> ellipk(3+4j)
4988 (0.9111955638049650086562171 + 0.6313342832413452438845091j)
4990A definite integral::
4992 >>> quad(ellipk, [0, 1])
4993 2.0
4994"""
4996agm = r"""
4997``agm(a, b)`` computes the arithmetic-geometric mean of `a` and
4998`b`, defined as the limit of the following iteration:
5000.. math ::
5002 a_0 = a
5004 b_0 = b
5006 a_{n+1} = \frac{a_n+b_n}{2}
5008 b_{n+1} = \sqrt{a_n b_n}
5010This function can be called with a single argument, computing
5011`\mathrm{agm}(a,1) = \mathrm{agm}(1,a)`.
5013**Examples**
5015It is a well-known theorem that the geometric mean of
5016two distinct positive numbers is less than the arithmetic
5017mean. It follows that the arithmetic-geometric mean lies
5018between the two means::
5020 >>> from mpmath import *
5021 >>> mp.dps = 15; mp.pretty = True
5022 >>> a = mpf(3)
5023 >>> b = mpf(4)
5024 >>> sqrt(a*b)
5025 3.46410161513775
5026 >>> agm(a,b)
5027 3.48202767635957
5028 >>> (a+b)/2
5029 3.5
5031The arithmetic-geometric mean is scale-invariant::
5033 >>> agm(10*e, 10*pi)
5034 29.261085515723
5035 >>> 10*agm(e, pi)
5036 29.261085515723
5038As an order-of-magnitude estimate, `\mathrm{agm}(1,x) \approx x`
5039for large `x`::
5041 >>> agm(10**10)
5042 643448704.760133
5043 >>> agm(10**50)
5044 1.34814309345871e+48
5046For tiny `x`, `\mathrm{agm}(1,x) \approx -\pi/(2 \log(x/4))`::
5048 >>> agm('0.01')
5049 0.262166887202249
5050 >>> -pi/2/log('0.0025')
5051 0.262172347753122
5053The arithmetic-geometric mean can also be computed for complex
5054numbers::
5056 >>> agm(3, 2+j)
5057 (2.51055133276184 + 0.547394054060638j)
5059The AGM iteration converges very quickly (each step doubles
5060the number of correct digits), so :func:`~mpmath.agm` supports efficient
5061high-precision evaluation::
5063 >>> mp.dps = 10000
5064 >>> a = agm(1,2)
5065 >>> str(a)[-10:]
5066 '1679581912'
5068**Mathematical relations**
5070The arithmetic-geometric mean may be used to evaluate the
5071following two parametric definite integrals:
5073.. math ::
5075 I_1 = \int_0^{\infty}
5076 \frac{1}{\sqrt{(x^2+a^2)(x^2+b^2)}} \,dx
5078 I_2 = \int_0^{\pi/2}
5079 \frac{1}{\sqrt{a^2 \cos^2(x) + b^2 \sin^2(x)}} \,dx
5081We have::
5083 >>> mp.dps = 15
5084 >>> a = 3
5085 >>> b = 4
5086 >>> f1 = lambda x: ((x**2+a**2)*(x**2+b**2))**-0.5
5087 >>> f2 = lambda x: ((a*cos(x))**2 + (b*sin(x))**2)**-0.5
5088 >>> quad(f1, [0, inf])
5089 0.451115405388492
5090 >>> quad(f2, [0, pi/2])
5091 0.451115405388492
5092 >>> pi/(2*agm(a,b))
5093 0.451115405388492
5095A formula for `\Gamma(1/4)`::
5097 >>> gamma(0.25)
5098 3.62560990822191
5099 >>> sqrt(2*sqrt(2*pi**3)/agm(1,sqrt(2)))
5100 3.62560990822191
5102**Possible issues**
5104The branch cut chosen for complex `a` and `b` is somewhat
5105arbitrary.
5107"""
5109gegenbauer = r"""
5110Evaluates the Gegenbauer polynomial, or ultraspherical polynomial,
5112.. math ::
5114 C_n^{(a)}(z) = {n+2a-1 \choose n} \,_2F_1\left(-n, n+2a;
5115 a+\frac{1}{2}; \frac{1}{2}(1-z)\right).
5117When `n` is a nonnegative integer, this formula gives a polynomial
5118in `z` of degree `n`, but all parameters are permitted to be
5119complex numbers. With `a = 1/2`, the Gegenbauer polynomial
5120reduces to a Legendre polynomial.
5122**Examples**
5124Evaluation for arbitrary arguments::
5126 >>> from mpmath import *
5127 >>> mp.dps = 25; mp.pretty = True
5128 >>> gegenbauer(3, 0.5, -10)
5129 -2485.0
5130 >>> gegenbauer(1000, 10, 100)
5131 3.012757178975667428359374e+2322
5132 >>> gegenbauer(2+3j, -0.75, -1000j)
5133 (-5038991.358609026523401901 + 9414549.285447104177860806j)
5135Evaluation at negative integer orders::
5137 >>> gegenbauer(-4, 2, 1.75)
5138 -1.0
5139 >>> gegenbauer(-4, 3, 1.75)
5140 0.0
5141 >>> gegenbauer(-4, 2j, 1.75)
5142 0.0
5143 >>> gegenbauer(-7, 0.5, 3)
5144 8989.0
5146The Gegenbauer polynomials solve the differential equation::
5148 >>> n, a = 4.5, 1+2j
5149 >>> f = lambda z: gegenbauer(n, a, z)
5150 >>> for z in [0, 0.75, -0.5j]:
5151 ... chop((1-z**2)*diff(f,z,2) - (2*a+1)*z*diff(f,z) + n*(n+2*a)*f(z))
5152 ...
5153 0.0
5154 0.0
5155 0.0
5157The Gegenbauer polynomials have generating function
5158`(1-2zt+t^2)^{-a}`::
5160 >>> a, z = 2.5, 1
5161 >>> taylor(lambda t: (1-2*z*t+t**2)**(-a), 0, 3)
5162 [1.0, 5.0, 15.0, 35.0]
5163 >>> [gegenbauer(n,a,z) for n in range(4)]
5164 [1.0, 5.0, 15.0, 35.0]
5166The Gegenbauer polynomials are orthogonal on `[-1, 1]` with respect
5167to the weight `(1-z^2)^{a-\frac{1}{2}}`::
5169 >>> a, n, m = 2.5, 4, 5
5170 >>> Cn = lambda z: gegenbauer(n, a, z, zeroprec=1000)
5171 >>> Cm = lambda z: gegenbauer(m, a, z, zeroprec=1000)
5172 >>> chop(quad(lambda z: Cn(z)*Cm(z)*(1-z**2)*(a-0.5), [-1, 1]))
5173 0.0
5174"""
5176laguerre = r"""
5177Gives the generalized (associated) Laguerre polynomial, defined by
5179.. math ::
5181 L_n^a(z) = \frac{\Gamma(n+b+1)}{\Gamma(b+1) \Gamma(n+1)}
5182 \,_1F_1(-n, a+1, z).
5184With `a = 0` and `n` a nonnegative integer, this reduces to an ordinary
5185Laguerre polynomial, the sequence of which begins
5186`L_0(z) = 1, L_1(z) = 1-z, L_2(z) = z^2-2z+1, \ldots`.
5188The Laguerre polynomials are orthogonal with respect to the weight
5189`z^a e^{-z}` on `[0, \infty)`.
5191**Plots**
5193.. literalinclude :: /plots/laguerre.py
5194.. image :: /plots/laguerre.png
5196**Examples**
5198Evaluation for arbitrary arguments::
5200 >>> from mpmath import *
5201 >>> mp.dps = 25; mp.pretty = True
5202 >>> laguerre(5, 0, 0.25)
5203 0.03726399739583333333333333
5204 >>> laguerre(1+j, 0.5, 2+3j)
5205 (4.474921610704496808379097 - 11.02058050372068958069241j)
5206 >>> laguerre(2, 0, 10000)
5207 49980001.0
5208 >>> laguerre(2.5, 0, 10000)
5209 -9.327764910194842158583189e+4328
5211The first few Laguerre polynomials, normalized to have integer
5212coefficients::
5214 >>> for n in range(7):
5215 ... chop(taylor(lambda z: fac(n)*laguerre(n, 0, z), 0, n))
5216 ...
5217 [1.0]
5218 [1.0, -1.0]
5219 [2.0, -4.0, 1.0]
5220 [6.0, -18.0, 9.0, -1.0]
5221 [24.0, -96.0, 72.0, -16.0, 1.0]
5222 [120.0, -600.0, 600.0, -200.0, 25.0, -1.0]
5223 [720.0, -4320.0, 5400.0, -2400.0, 450.0, -36.0, 1.0]
5225Verifying orthogonality::
5227 >>> Lm = lambda t: laguerre(m,a,t)
5228 >>> Ln = lambda t: laguerre(n,a,t)
5229 >>> a, n, m = 2.5, 2, 3
5230 >>> chop(quad(lambda t: exp(-t)*t**a*Lm(t)*Ln(t), [0,inf]))
5231 0.0
5234"""
5236hermite = r"""
5237Evaluates the Hermite polynomial `H_n(z)`, which may be defined using
5238the recurrence
5240.. math ::
5242 H_0(z) = 1
5244 H_1(z) = 2z
5246 H_{n+1} = 2z H_n(z) - 2n H_{n-1}(z).
5248The Hermite polynomials are orthogonal on `(-\infty, \infty)` with
5249respect to the weight `e^{-z^2}`. More generally, allowing arbitrary complex
5250values of `n`, the Hermite function `H_n(z)` is defined as
5252.. math ::
5254 H_n(z) = (2z)^n \,_2F_0\left(-\frac{n}{2}, \frac{1-n}{2},
5255 -\frac{1}{z^2}\right)
5257for `\Re{z} > 0`, or generally
5259.. math ::
5261 H_n(z) = 2^n \sqrt{\pi} \left(
5262 \frac{1}{\Gamma\left(\frac{1-n}{2}\right)}
5263 \,_1F_1\left(-\frac{n}{2}, \frac{1}{2}, z^2\right) -
5264 \frac{2z}{\Gamma\left(-\frac{n}{2}\right)}
5265 \,_1F_1\left(\frac{1-n}{2}, \frac{3}{2}, z^2\right)
5266 \right).
5268**Plots**
5270.. literalinclude :: /plots/hermite.py
5271.. image :: /plots/hermite.png
5273**Examples**
5275Evaluation for arbitrary arguments::
5277 >>> from mpmath import *
5278 >>> mp.dps = 25; mp.pretty = True
5279 >>> hermite(0, 10)
5280 1.0
5281 >>> hermite(1, 10); hermite(2, 10)
5282 20.0
5283 398.0
5284 >>> hermite(10000, 2)
5285 4.950440066552087387515653e+19334
5286 >>> hermite(3, -10**8)
5287 -7999999999999998800000000.0
5288 >>> hermite(-3, -10**8)
5289 1.675159751729877682920301e+4342944819032534
5290 >>> hermite(2+3j, -1+2j)
5291 (-0.07652130602993513389421901 - 0.1084662449961914580276007j)
5293Coefficients of the first few Hermite polynomials are::
5295 >>> for n in range(7):
5296 ... chop(taylor(lambda z: hermite(n, z), 0, n))
5297 ...
5298 [1.0]
5299 [0.0, 2.0]
5300 [-2.0, 0.0, 4.0]
5301 [0.0, -12.0, 0.0, 8.0]
5302 [12.0, 0.0, -48.0, 0.0, 16.0]
5303 [0.0, 120.0, 0.0, -160.0, 0.0, 32.0]
5304 [-120.0, 0.0, 720.0, 0.0, -480.0, 0.0, 64.0]
5306Values at `z = 0`::
5308 >>> for n in range(-5, 9):
5309 ... hermite(n, 0)
5310 ...
5311 0.02769459142039868792653387
5312 0.08333333333333333333333333
5313 0.2215567313631895034122709
5314 0.5
5315 0.8862269254527580136490837
5316 1.0
5317 0.0
5318 -2.0
5319 0.0
5320 12.0
5321 0.0
5322 -120.0
5323 0.0
5324 1680.0
5326Hermite functions satisfy the differential equation::
5328 >>> n = 4
5329 >>> f = lambda z: hermite(n, z)
5330 >>> z = 1.5
5331 >>> chop(diff(f,z,2) - 2*z*diff(f,z) + 2*n*f(z))
5332 0.0
5334Verifying orthogonality::
5336 >>> chop(quad(lambda t: hermite(2,t)*hermite(4,t)*exp(-t**2), [-inf,inf]))
5337 0.0
5339"""
5341jacobi = r"""
5342``jacobi(n, a, b, x)`` evaluates the Jacobi polynomial
5343`P_n^{(a,b)}(x)`. The Jacobi polynomials are a special
5344case of the hypergeometric function `\,_2F_1` given by:
5346.. math ::
5348 P_n^{(a,b)}(x) = {n+a \choose n}
5349 \,_2F_1\left(-n,1+a+b+n,a+1,\frac{1-x}{2}\right).
5351Note that this definition generalizes to nonintegral values
5352of `n`. When `n` is an integer, the hypergeometric series
5353terminates after a finite number of terms, giving
5354a polynomial in `x`.
5356**Evaluation of Jacobi polynomials**
5358A special evaluation is `P_n^{(a,b)}(1) = {n+a \choose n}`::
5360 >>> from mpmath import *
5361 >>> mp.dps = 15; mp.pretty = True
5362 >>> jacobi(4, 0.5, 0.25, 1)
5363 2.4609375
5364 >>> binomial(4+0.5, 4)
5365 2.4609375
5367A Jacobi polynomial of degree `n` is equal to its
5368Taylor polynomial of degree `n`. The explicit
5369coefficients of Jacobi polynomials can therefore
5370be recovered easily using :func:`~mpmath.taylor`::
5372 >>> for n in range(5):
5373 ... nprint(taylor(lambda x: jacobi(n,1,2,x), 0, n))
5374 ...
5375 [1.0]
5376 [-0.5, 2.5]
5377 [-0.75, -1.5, 5.25]
5378 [0.5, -3.5, -3.5, 10.5]
5379 [0.625, 2.5, -11.25, -7.5, 20.625]
5381For nonintegral `n`, the Jacobi "polynomial" is no longer
5382a polynomial::
5384 >>> nprint(taylor(lambda x: jacobi(0.5,1,2,x), 0, 4))
5385 [0.309983, 1.84119, -1.26933, 1.26699, -1.34808]
5387**Orthogonality**
5389The Jacobi polynomials are orthogonal on the interval
5390`[-1, 1]` with respect to the weight function
5391`w(x) = (1-x)^a (1+x)^b`. That is,
5392`w(x) P_n^{(a,b)}(x) P_m^{(a,b)}(x)` integrates to
5393zero if `m \ne n` and to a nonzero number if `m = n`.
5395The orthogonality is easy to verify using numerical
5396quadrature::
5398 >>> P = jacobi
5399 >>> f = lambda x: (1-x)**a * (1+x)**b * P(m,a,b,x) * P(n,a,b,x)
5400 >>> a = 2
5401 >>> b = 3
5402 >>> m, n = 3, 4
5403 >>> chop(quad(f, [-1, 1]), 1)
5404 0.0
5405 >>> m, n = 4, 4
5406 >>> quad(f, [-1, 1])
5407 1.9047619047619
5409**Differential equation**
5411The Jacobi polynomials are solutions of the differential
5412equation
5414.. math ::
5416 (1-x^2) y'' + (b-a-(a+b+2)x) y' + n (n+a+b+1) y = 0.
5418We can verify that :func:`~mpmath.jacobi` approximately satisfies
5419this equation::
5421 >>> from mpmath import *
5422 >>> mp.dps = 15
5423 >>> a = 2.5
5424 >>> b = 4
5425 >>> n = 3
5426 >>> y = lambda x: jacobi(n,a,b,x)
5427 >>> x = pi
5428 >>> A0 = n*(n+a+b+1)*y(x)
5429 >>> A1 = (b-a-(a+b+2)*x)*diff(y,x)
5430 >>> A2 = (1-x**2)*diff(y,x,2)
5431 >>> nprint(A2 + A1 + A0, 1)
5432 4.0e-12
5434The difference of order `10^{-12}` is as close to zero as
5435it could be at 15-digit working precision, since the terms
5436are large::
5438 >>> A0, A1, A2
5439 (26560.2328981879, -21503.7641037294, -5056.46879445852)
5441"""
5443legendre = r"""
5444``legendre(n, x)`` evaluates the Legendre polynomial `P_n(x)`.
5445The Legendre polynomials are given by the formula
5447.. math ::
5449 P_n(x) = \frac{1}{2^n n!} \frac{d^n}{dx^n} (x^2 -1)^n.
5451Alternatively, they can be computed recursively using
5453.. math ::
5455 P_0(x) = 1
5457 P_1(x) = x
5459 (n+1) P_{n+1}(x) = (2n+1) x P_n(x) - n P_{n-1}(x).
5461A third definition is in terms of the hypergeometric function
5462`\,_2F_1`, whereby they can be generalized to arbitrary `n`:
5464.. math ::
5466 P_n(x) = \,_2F_1\left(-n, n+1, 1, \frac{1-x}{2}\right)
5468**Plots**
5470.. literalinclude :: /plots/legendre.py
5471.. image :: /plots/legendre.png
5473**Basic evaluation**
5475The Legendre polynomials assume fixed values at the points
5476`x = -1` and `x = 1`::
5478 >>> from mpmath import *
5479 >>> mp.dps = 15; mp.pretty = True
5480 >>> nprint([legendre(n, 1) for n in range(6)])
5481 [1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
5482 >>> nprint([legendre(n, -1) for n in range(6)])
5483 [1.0, -1.0, 1.0, -1.0, 1.0, -1.0]
5485The coefficients of Legendre polynomials can be recovered
5486using degree-`n` Taylor expansion::
5488 >>> for n in range(5):
5489 ... nprint(chop(taylor(lambda x: legendre(n, x), 0, n)))
5490 ...
5491 [1.0]
5492 [0.0, 1.0]
5493 [-0.5, 0.0, 1.5]
5494 [0.0, -1.5, 0.0, 2.5]
5495 [0.375, 0.0, -3.75, 0.0, 4.375]
5497The roots of Legendre polynomials are located symmetrically
5498on the interval `[-1, 1]`::
5500 >>> for n in range(5):
5501 ... nprint(polyroots(taylor(lambda x: legendre(n, x), 0, n)[::-1]))
5502 ...
5503 []
5504 [0.0]
5505 [-0.57735, 0.57735]
5506 [-0.774597, 0.0, 0.774597]
5507 [-0.861136, -0.339981, 0.339981, 0.861136]
5509An example of an evaluation for arbitrary `n`::
5511 >>> legendre(0.75, 2+4j)
5512 (1.94952805264875 + 2.1071073099422j)
5514**Orthogonality**
5516The Legendre polynomials are orthogonal on `[-1, 1]` with respect
5517to the trivial weight `w(x) = 1`. That is, `P_m(x) P_n(x)`
5518integrates to zero if `m \ne n` and to `2/(2n+1)` if `m = n`::
5520 >>> m, n = 3, 4
5521 >>> quad(lambda x: legendre(m,x)*legendre(n,x), [-1, 1])
5522 0.0
5523 >>> m, n = 4, 4
5524 >>> quad(lambda x: legendre(m,x)*legendre(n,x), [-1, 1])
5525 0.222222222222222
5527**Differential equation**
5529The Legendre polynomials satisfy the differential equation
5531.. math ::
5533 ((1-x^2) y')' + n(n+1) y' = 0.
5535We can verify this numerically::
5537 >>> n = 3.6
5538 >>> x = 0.73
5539 >>> P = legendre
5540 >>> A = diff(lambda t: (1-t**2)*diff(lambda u: P(n,u), t), x)
5541 >>> B = n*(n+1)*P(n,x)
5542 >>> nprint(A+B,1)
5543 9.0e-16
5545"""
5548legenp = r"""
5549Calculates the (associated) Legendre function of the first kind of
5550degree *n* and order *m*, `P_n^m(z)`. Taking `m = 0` gives the ordinary
5551Legendre function of the first kind, `P_n(z)`. The parameters may be
5552complex numbers.
5554In terms of the Gauss hypergeometric function, the (associated) Legendre
5555function is defined as
5557.. math ::
5559 P_n^m(z) = \frac{1}{\Gamma(1-m)} \frac{(1+z)^{m/2}}{(1-z)^{m/2}}
5560 \,_2F_1\left(-n, n+1, 1-m, \frac{1-z}{2}\right).
5562With *type=3* instead of *type=2*, the alternative
5563definition
5565.. math ::
5567 \hat{P}_n^m(z) = \frac{1}{\Gamma(1-m)} \frac{(z+1)^{m/2}}{(z-1)^{m/2}}
5568 \,_2F_1\left(-n, n+1, 1-m, \frac{1-z}{2}\right).
5570is used. These functions correspond respectively to ``LegendreP[n,m,2,z]``
5571and ``LegendreP[n,m,3,z]`` in Mathematica.
5573The general solution of the (associated) Legendre differential equation
5575.. math ::
5577 (1-z^2) f''(z) - 2zf'(z) + \left(n(n+1)-\frac{m^2}{1-z^2}\right)f(z) = 0
5579is given by `C_1 P_n^m(z) + C_2 Q_n^m(z)` for arbitrary constants
5580`C_1`, `C_2`, where `Q_n^m(z)` is a Legendre function of the
5581second kind as implemented by :func:`~mpmath.legenq`.
5583**Examples**
5585Evaluation for arbitrary parameters and arguments::
5587 >>> from mpmath import *
5588 >>> mp.dps = 25; mp.pretty = True
5589 >>> legenp(2, 0, 10); legendre(2, 10)
5590 149.5
5591 149.5
5592 >>> legenp(-2, 0.5, 2.5)
5593 (1.972260393822275434196053 - 1.972260393822275434196053j)
5594 >>> legenp(2+3j, 1-j, -0.5+4j)
5595 (-3.335677248386698208736542 - 5.663270217461022307645625j)
5596 >>> chop(legenp(3, 2, -1.5, type=2))
5597 28.125
5598 >>> chop(legenp(3, 2, -1.5, type=3))
5599 -28.125
5601Verifying the associated Legendre differential equation::
5603 >>> n, m = 2, -0.5
5604 >>> C1, C2 = 1, -3
5605 >>> f = lambda z: C1*legenp(n,m,z) + C2*legenq(n,m,z)
5606 >>> deq = lambda z: (1-z**2)*diff(f,z,2) - 2*z*diff(f,z) + \
5607 ... (n*(n+1)-m**2/(1-z**2))*f(z)
5608 >>> for z in [0, 2, -1.5, 0.5+2j]:
5609 ... chop(deq(mpmathify(z)))
5610 ...
5611 0.0
5612 0.0
5613 0.0
5614 0.0
5615"""
5617legenq = r"""
5618Calculates the (associated) Legendre function of the second kind of
5619degree *n* and order *m*, `Q_n^m(z)`. Taking `m = 0` gives the ordinary
5620Legendre function of the second kind, `Q_n(z)`. The parameters may be
5621complex numbers.
5623The Legendre functions of the second kind give a second set of
5624solutions to the (associated) Legendre differential equation.
5625(See :func:`~mpmath.legenp`.)
5626Unlike the Legendre functions of the first kind, they are not
5627polynomials of `z` for integer `n`, `m` but rational or logarithmic
5628functions with poles at `z = \pm 1`.
5630There are various ways to define Legendre functions of
5631the second kind, giving rise to different complex structure.
5632A version can be selected using the *type* keyword argument.
5633The *type=2* and *type=3* functions are given respectively by
5635.. math ::
5637 Q_n^m(z) = \frac{\pi}{2 \sin(\pi m)}
5638 \left( \cos(\pi m) P_n^m(z) -
5639 \frac{\Gamma(1+m+n)}{\Gamma(1-m+n)} P_n^{-m}(z)\right)
5641 \hat{Q}_n^m(z) = \frac{\pi}{2 \sin(\pi m)} e^{\pi i m}
5642 \left( \hat{P}_n^m(z) -
5643 \frac{\Gamma(1+m+n)}{\Gamma(1-m+n)} \hat{P}_n^{-m}(z)\right)
5645where `P` and `\hat{P}` are the *type=2* and *type=3* Legendre functions
5646of the first kind. The formulas above should be understood as limits
5647when `m` is an integer.
5649These functions correspond to ``LegendreQ[n,m,2,z]`` (or ``LegendreQ[n,m,z]``)
5650and ``LegendreQ[n,m,3,z]`` in Mathematica. The *type=3* function
5651is essentially the same as the function defined in
5652Abramowitz & Stegun (eq. 8.1.3) but with `(z+1)^{m/2}(z-1)^{m/2}` instead
5653of `(z^2-1)^{m/2}`, giving slightly different branches.
5655**Examples**
5657Evaluation for arbitrary parameters and arguments::
5659 >>> from mpmath import *
5660 >>> mp.dps = 25; mp.pretty = True
5661 >>> legenq(2, 0, 0.5)
5662 -0.8186632680417568557122028
5663 >>> legenq(-1.5, -2, 2.5)
5664 (0.6655964618250228714288277 + 0.3937692045497259717762649j)
5665 >>> legenq(2-j, 3+4j, -6+5j)
5666 (-10001.95256487468541686564 - 6011.691337610097577791134j)
5668Different versions of the function::
5670 >>> legenq(2, 1, 0.5)
5671 0.7298060598018049369381857
5672 >>> legenq(2, 1, 1.5)
5673 (-7.902916572420817192300921 + 0.1998650072605976600724502j)
5674 >>> legenq(2, 1, 0.5, type=3)
5675 (2.040524284763495081918338 - 0.7298060598018049369381857j)
5676 >>> chop(legenq(2, 1, 1.5, type=3))
5677 -0.1998650072605976600724502
5679"""
5681chebyt = r"""
5682``chebyt(n, x)`` evaluates the Chebyshev polynomial of the first
5683kind `T_n(x)`, defined by the identity
5685.. math ::
5687 T_n(\cos x) = \cos(n x).
5689The Chebyshev polynomials of the first kind are a special
5690case of the Jacobi polynomials, and by extension of the
5691hypergeometric function `\,_2F_1`. They can thus also be
5692evaluated for nonintegral `n`.
5694**Plots**
5696.. literalinclude :: /plots/chebyt.py
5697.. image :: /plots/chebyt.png
5699**Basic evaluation**
5701The coefficients of the `n`-th polynomial can be recovered
5702using using degree-`n` Taylor expansion::
5704 >>> from mpmath import *
5705 >>> mp.dps = 15; mp.pretty = True
5706 >>> for n in range(5):
5707 ... nprint(chop(taylor(lambda x: chebyt(n, x), 0, n)))
5708 ...
5709 [1.0]
5710 [0.0, 1.0]
5711 [-1.0, 0.0, 2.0]
5712 [0.0, -3.0, 0.0, 4.0]
5713 [1.0, 0.0, -8.0, 0.0, 8.0]
5715**Orthogonality**
5717The Chebyshev polynomials of the first kind are orthogonal
5718on the interval `[-1, 1]` with respect to the weight
5719function `w(x) = 1/\sqrt{1-x^2}`::
5721 >>> f = lambda x: chebyt(m,x)*chebyt(n,x)/sqrt(1-x**2)
5722 >>> m, n = 3, 4
5723 >>> nprint(quad(f, [-1, 1]),1)
5724 0.0
5725 >>> m, n = 4, 4
5726 >>> quad(f, [-1, 1])
5727 1.57079632596448
5729"""
5731chebyu = r"""
5732``chebyu(n, x)`` evaluates the Chebyshev polynomial of the second
5733kind `U_n(x)`, defined by the identity
5735.. math ::
5737 U_n(\cos x) = \frac{\sin((n+1)x)}{\sin(x)}.
5739The Chebyshev polynomials of the second kind are a special
5740case of the Jacobi polynomials, and by extension of the
5741hypergeometric function `\,_2F_1`. They can thus also be
5742evaluated for nonintegral `n`.
5744**Plots**
5746.. literalinclude :: /plots/chebyu.py
5747.. image :: /plots/chebyu.png
5749**Basic evaluation**
5751The coefficients of the `n`-th polynomial can be recovered
5752using using degree-`n` Taylor expansion::
5754 >>> from mpmath import *
5755 >>> mp.dps = 15; mp.pretty = True
5756 >>> for n in range(5):
5757 ... nprint(chop(taylor(lambda x: chebyu(n, x), 0, n)))
5758 ...
5759 [1.0]
5760 [0.0, 2.0]
5761 [-1.0, 0.0, 4.0]
5762 [0.0, -4.0, 0.0, 8.0]
5763 [1.0, 0.0, -12.0, 0.0, 16.0]
5765**Orthogonality**
5767The Chebyshev polynomials of the second kind are orthogonal
5768on the interval `[-1, 1]` with respect to the weight
5769function `w(x) = \sqrt{1-x^2}`::
5771 >>> f = lambda x: chebyu(m,x)*chebyu(n,x)*sqrt(1-x**2)
5772 >>> m, n = 3, 4
5773 >>> quad(f, [-1, 1])
5774 0.0
5775 >>> m, n = 4, 4
5776 >>> quad(f, [-1, 1])
5777 1.5707963267949
5778"""
5780besselj = r"""
5781``besselj(n, x, derivative=0)`` gives the Bessel function of the first kind
5782`J_n(x)`. Bessel functions of the first kind are defined as
5783solutions of the differential equation
5785.. math ::
5787 x^2 y'' + x y' + (x^2 - n^2) y = 0
5789which appears, among other things, when solving the radial
5790part of Laplace's equation in cylindrical coordinates. This
5791equation has two solutions for given `n`, where the
5792`J_n`-function is the solution that is nonsingular at `x = 0`.
5793For positive integer `n`, `J_n(x)` behaves roughly like a sine
5794(odd `n`) or cosine (even `n`) multiplied by a magnitude factor
5795that decays slowly as `x \to \pm\infty`.
5797Generally, `J_n` is a special case of the hypergeometric
5798function `\,_0F_1`:
5800.. math ::
5802 J_n(x) = \frac{x^n}{2^n \Gamma(n+1)}
5803 \,_0F_1\left(n+1,-\frac{x^2}{4}\right)
5805With *derivative* = `m \ne 0`, the `m`-th derivative
5807.. math ::
5809 \frac{d^m}{dx^m} J_n(x)
5811is computed.
5813**Plots**
5815.. literalinclude :: /plots/besselj.py
5816.. image :: /plots/besselj.png
5817.. literalinclude :: /plots/besselj_c.py
5818.. image :: /plots/besselj_c.png
5820**Examples**
5822Evaluation is supported for arbitrary arguments, and at
5823arbitrary precision::
5825 >>> from mpmath import *
5826 >>> mp.dps = 15; mp.pretty = True
5827 >>> besselj(2, 1000)
5828 -0.024777229528606
5829 >>> besselj(4, 0.75)
5830 0.000801070086542314
5831 >>> besselj(2, 1000j)
5832 (-2.48071721019185e+432 + 6.41567059811949e-437j)
5833 >>> mp.dps = 25
5834 >>> besselj(0.75j, 3+4j)
5835 (-2.778118364828153309919653 - 1.5863603889018621585533j)
5836 >>> mp.dps = 50
5837 >>> besselj(1, pi)
5838 0.28461534317975275734531059968613140570981118184947
5840Arguments may be large::
5842 >>> mp.dps = 25
5843 >>> besselj(0, 10000)
5844 -0.007096160353388801477265164
5845 >>> besselj(0, 10**10)
5846 0.000002175591750246891726859055
5847 >>> besselj(2, 10**100)
5848 7.337048736538615712436929e-51
5849 >>> besselj(2, 10**5*j)
5850 (-3.540725411970948860173735e+43426 + 4.4949812409615803110051e-43433j)
5852The Bessel functions of the first kind satisfy simple
5853symmetries around `x = 0`::
5855 >>> mp.dps = 15
5856 >>> nprint([besselj(n,0) for n in range(5)])
5857 [1.0, 0.0, 0.0, 0.0, 0.0]
5858 >>> nprint([besselj(n,pi) for n in range(5)])
5859 [-0.304242, 0.284615, 0.485434, 0.333458, 0.151425]
5860 >>> nprint([besselj(n,-pi) for n in range(5)])
5861 [-0.304242, -0.284615, 0.485434, -0.333458, 0.151425]
5863Roots of Bessel functions are often used::
5865 >>> nprint([findroot(j0, k) for k in [2, 5, 8, 11, 14]])
5866 [2.40483, 5.52008, 8.65373, 11.7915, 14.9309]
5867 >>> nprint([findroot(j1, k) for k in [3, 7, 10, 13, 16]])
5868 [3.83171, 7.01559, 10.1735, 13.3237, 16.4706]
5870The roots are not periodic, but the distance between successive
5871roots asymptotically approaches `2 \pi`. Bessel functions of
5872the first kind have the following normalization::
5874 >>> quadosc(j0, [0, inf], period=2*pi)
5875 1.0
5876 >>> quadosc(j1, [0, inf], period=2*pi)
5877 1.0
5879For `n = 1/2` or `n = -1/2`, the Bessel function reduces to a
5880trigonometric function::
5882 >>> x = 10
5883 >>> besselj(0.5, x), sqrt(2/(pi*x))*sin(x)
5884 (-0.13726373575505, -0.13726373575505)
5885 >>> besselj(-0.5, x), sqrt(2/(pi*x))*cos(x)
5886 (-0.211708866331398, -0.211708866331398)
5888Derivatives of any order can be computed (negative orders
5889correspond to integration)::
5891 >>> mp.dps = 25
5892 >>> besselj(0, 7.5, 1)
5893 -0.1352484275797055051822405
5894 >>> diff(lambda x: besselj(0,x), 7.5)
5895 -0.1352484275797055051822405
5896 >>> besselj(0, 7.5, 10)
5897 -0.1377811164763244890135677
5898 >>> diff(lambda x: besselj(0,x), 7.5, 10)
5899 -0.1377811164763244890135677
5900 >>> besselj(0,7.5,-1) - besselj(0,3.5,-1)
5901 -0.1241343240399987693521378
5902 >>> quad(j0, [3.5, 7.5])
5903 -0.1241343240399987693521378
5905Differentiation with a noninteger order gives the fractional derivative
5906in the sense of the Riemann-Liouville differintegral, as computed by
5907:func:`~mpmath.differint`::
5909 >>> mp.dps = 15
5910 >>> besselj(1, 3.5, 0.75)
5911 -0.385977722939384
5912 >>> differint(lambda x: besselj(1, x), 3.5, 0.75)
5913 -0.385977722939384
5915"""
5917besseli = r"""
5918``besseli(n, x, derivative=0)`` gives the modified Bessel function of the
5919first kind,
5921.. math ::
5923 I_n(x) = i^{-n} J_n(ix).
5925With *derivative* = `m \ne 0`, the `m`-th derivative
5927.. math ::
5929 \frac{d^m}{dx^m} I_n(x)
5931is computed.
5933**Plots**
5935.. literalinclude :: /plots/besseli.py
5936.. image :: /plots/besseli.png
5937.. literalinclude :: /plots/besseli_c.py
5938.. image :: /plots/besseli_c.png
5940**Examples**
5942Some values of `I_n(x)`::
5944 >>> from mpmath import *
5945 >>> mp.dps = 25; mp.pretty = True
5946 >>> besseli(0,0)
5947 1.0
5948 >>> besseli(1,0)
5949 0.0
5950 >>> besseli(0,1)
5951 1.266065877752008335598245
5952 >>> besseli(3.5, 2+3j)
5953 (-0.2904369752642538144289025 - 0.4469098397654815837307006j)
5955Arguments may be large::
5957 >>> besseli(2, 1000)
5958 2.480717210191852440616782e+432
5959 >>> besseli(2, 10**10)
5960 4.299602851624027900335391e+4342944813
5961 >>> besseli(2, 6000+10000j)
5962 (-2.114650753239580827144204e+2603 + 4.385040221241629041351886e+2602j)
5964For integers `n`, the following integral representation holds::
5966 >>> mp.dps = 15
5967 >>> n = 3
5968 >>> x = 2.3
5969 >>> quad(lambda t: exp(x*cos(t))*cos(n*t), [0,pi])/pi
5970 0.349223221159309
5971 >>> besseli(n,x)
5972 0.349223221159309
5974Derivatives and antiderivatives of any order can be computed::
5976 >>> mp.dps = 25
5977 >>> besseli(2, 7.5, 1)
5978 195.8229038931399062565883
5979 >>> diff(lambda x: besseli(2,x), 7.5)
5980 195.8229038931399062565883
5981 >>> besseli(2, 7.5, 10)
5982 153.3296508971734525525176
5983 >>> diff(lambda x: besseli(2,x), 7.5, 10)
5984 153.3296508971734525525176
5985 >>> besseli(2,7.5,-1) - besseli(2,3.5,-1)
5986 202.5043900051930141956876
5987 >>> quad(lambda x: besseli(2,x), [3.5, 7.5])
5988 202.5043900051930141956876
5990"""
5992bessely = r"""
5993``bessely(n, x, derivative=0)`` gives the Bessel function of the second kind,
5995.. math ::
5997 Y_n(x) = \frac{J_n(x) \cos(\pi n) - J_{-n}(x)}{\sin(\pi n)}.
5999For `n` an integer, this formula should be understood as a
6000limit. With *derivative* = `m \ne 0`, the `m`-th derivative
6002.. math ::
6004 \frac{d^m}{dx^m} Y_n(x)
6006is computed.
6008**Plots**
6010.. literalinclude :: /plots/bessely.py
6011.. image :: /plots/bessely.png
6012.. literalinclude :: /plots/bessely_c.py
6013.. image :: /plots/bessely_c.png
6015**Examples**
6017Some values of `Y_n(x)`::
6019 >>> from mpmath import *
6020 >>> mp.dps = 25; mp.pretty = True
6021 >>> bessely(0,0), bessely(1,0), bessely(2,0)
6022 (-inf, -inf, -inf)
6023 >>> bessely(1, pi)
6024 0.3588729167767189594679827
6025 >>> bessely(0.5, 3+4j)
6026 (9.242861436961450520325216 - 3.085042824915332562522402j)
6028Arguments may be large::
6030 >>> bessely(0, 10000)
6031 0.00364780555898660588668872
6032 >>> bessely(2.5, 10**50)
6033 -4.8952500412050989295774e-26
6034 >>> bessely(2.5, -10**50)
6035 (0.0 + 4.8952500412050989295774e-26j)
6037Derivatives and antiderivatives of any order can be computed::
6039 >>> bessely(2, 3.5, 1)
6040 0.3842618820422660066089231
6041 >>> diff(lambda x: bessely(2, x), 3.5)
6042 0.3842618820422660066089231
6043 >>> bessely(0.5, 3.5, 1)
6044 -0.2066598304156764337900417
6045 >>> diff(lambda x: bessely(0.5, x), 3.5)
6046 -0.2066598304156764337900417
6047 >>> diff(lambda x: bessely(2, x), 0.5, 10)
6048 -208173867409.5547350101511
6049 >>> bessely(2, 0.5, 10)
6050 -208173867409.5547350101511
6051 >>> bessely(2, 100.5, 100)
6052 0.02668487547301372334849043
6053 >>> quad(lambda x: bessely(2,x), [1,3])
6054 -1.377046859093181969213262
6055 >>> bessely(2,3,-1) - bessely(2,1,-1)
6056 -1.377046859093181969213262
6058"""
6060besselk = r"""
6061``besselk(n, x)`` gives the modified Bessel function of the
6062second kind,
6064.. math ::
6066 K_n(x) = \frac{\pi}{2} \frac{I_{-n}(x)-I_{n}(x)}{\sin(\pi n)}
6068For `n` an integer, this formula should be understood as a
6069limit.
6071**Plots**
6073.. literalinclude :: /plots/besselk.py
6074.. image :: /plots/besselk.png
6075.. literalinclude :: /plots/besselk_c.py
6076.. image :: /plots/besselk_c.png
6078**Examples**
6080Evaluation is supported for arbitrary complex arguments::
6082 >>> from mpmath import *
6083 >>> mp.dps = 25; mp.pretty = True
6084 >>> besselk(0,1)
6085 0.4210244382407083333356274
6086 >>> besselk(0, -1)
6087 (0.4210244382407083333356274 - 3.97746326050642263725661j)
6088 >>> besselk(3.5, 2+3j)
6089 (-0.02090732889633760668464128 + 0.2464022641351420167819697j)
6090 >>> besselk(2+3j, 0.5)
6091 (0.9615816021726349402626083 + 0.1918250181801757416908224j)
6093Arguments may be large::
6095 >>> besselk(0, 100)
6096 4.656628229175902018939005e-45
6097 >>> besselk(1, 10**6)
6098 4.131967049321725588398296e-434298
6099 >>> besselk(1, 10**6*j)
6100 (0.001140348428252385844876706 - 0.0005200017201681152909000961j)
6101 >>> besselk(4.5, fmul(10**50, j, exact=True))
6102 (1.561034538142413947789221e-26 + 1.243554598118700063281496e-25j)
6104The point `x = 0` is a singularity (logarithmic if `n = 0`)::
6106 >>> besselk(0,0)
6107 +inf
6108 >>> besselk(1,0)
6109 +inf
6110 >>> for n in range(-4, 5):
6111 ... print(besselk(n, '1e-1000'))
6112 ...
6113 4.8e+4001
6114 8.0e+3000
6115 2.0e+2000
6116 1.0e+1000
6117 2302.701024509704096466802
6118 1.0e+1000
6119 2.0e+2000
6120 8.0e+3000
6121 4.8e+4001
6123"""
6125hankel1 = r"""
6126``hankel1(n,x)`` computes the Hankel function of the first kind,
6127which is the complex combination of Bessel functions given by
6129.. math ::
6131 H_n^{(1)}(x) = J_n(x) + i Y_n(x).
6133**Plots**
6135.. literalinclude :: /plots/hankel1.py
6136.. image :: /plots/hankel1.png
6137.. literalinclude :: /plots/hankel1_c.py
6138.. image :: /plots/hankel1_c.png
6140**Examples**
6142The Hankel function is generally complex-valued::
6144 >>> from mpmath import *
6145 >>> mp.dps = 25; mp.pretty = True
6146 >>> hankel1(2, pi)
6147 (0.4854339326315091097054957 - 0.0999007139290278787734903j)
6148 >>> hankel1(3.5, pi)
6149 (0.2340002029630507922628888 - 0.6419643823412927142424049j)
6150"""
6152hankel2 = r"""
6153``hankel2(n,x)`` computes the Hankel function of the second kind,
6154which is the complex combination of Bessel functions given by
6156.. math ::
6158 H_n^{(2)}(x) = J_n(x) - i Y_n(x).
6160**Plots**
6162.. literalinclude :: /plots/hankel2.py
6163.. image :: /plots/hankel2.png
6164.. literalinclude :: /plots/hankel2_c.py
6165.. image :: /plots/hankel2_c.png
6167**Examples**
6169The Hankel function is generally complex-valued::
6171 >>> from mpmath import *
6172 >>> mp.dps = 25; mp.pretty = True
6173 >>> hankel2(2, pi)
6174 (0.4854339326315091097054957 + 0.0999007139290278787734903j)
6175 >>> hankel2(3.5, pi)
6176 (0.2340002029630507922628888 + 0.6419643823412927142424049j)
6177"""
6179lambertw = r"""
6180The Lambert W function `W(z)` is defined as the inverse function
6181of `w \exp(w)`. In other words, the value of `W(z)` is such that
6182`z = W(z) \exp(W(z))` for any complex number `z`.
6184The Lambert W function is a multivalued function with infinitely
6185many branches `W_k(z)`, indexed by `k \in \mathbb{Z}`. Each branch
6186gives a different solution `w` of the equation `z = w \exp(w)`.
6187All branches are supported by :func:`~mpmath.lambertw`:
6189* ``lambertw(z)`` gives the principal solution (branch 0)
6191* ``lambertw(z, k)`` gives the solution on branch `k`
6193The Lambert W function has two partially real branches: the
6194principal branch (`k = 0`) is real for real `z > -1/e`, and the
6195`k = -1` branch is real for `-1/e < z < 0`. All branches except
6196`k = 0` have a logarithmic singularity at `z = 0`.
6198The definition, implementation and choice of branches
6199is based on [Corless]_.
6201**Plots**
6203.. literalinclude :: /plots/lambertw.py
6204.. image :: /plots/lambertw.png
6205.. literalinclude :: /plots/lambertw_c.py
6206.. image :: /plots/lambertw_c.png
6208**Basic examples**
6210The Lambert W function is the inverse of `w \exp(w)`::
6212 >>> from mpmath import *
6213 >>> mp.dps = 25; mp.pretty = True
6214 >>> w = lambertw(1)
6215 >>> w
6216 0.5671432904097838729999687
6217 >>> w*exp(w)
6218 1.0
6220Any branch gives a valid inverse::
6222 >>> w = lambertw(1, k=3)
6223 >>> w
6224 (-2.853581755409037807206819 + 17.11353553941214591260783j)
6225 >>> w = lambertw(1, k=25)
6226 >>> w
6227 (-5.047020464221569709378686 + 155.4763860949415867162066j)
6228 >>> chop(w*exp(w))
6229 1.0
6231**Applications to equation-solving**
6233The Lambert W function may be used to solve various kinds of
6234equations, such as finding the value of the infinite power
6235tower `z^{z^{z^{\ldots}}}`::
6237 >>> def tower(z, n):
6238 ... if n == 0:
6239 ... return z
6240 ... return z ** tower(z, n-1)
6241 ...
6242 >>> tower(mpf(0.5), 100)
6243 0.6411857445049859844862005
6244 >>> -lambertw(-log(0.5))/log(0.5)
6245 0.6411857445049859844862005
6247**Properties**
6249The Lambert W function grows roughly like the natural logarithm
6250for large arguments::
6252 >>> lambertw(1000); log(1000)
6253 5.249602852401596227126056
6254 6.907755278982137052053974
6255 >>> lambertw(10**100); log(10**100)
6256 224.8431064451185015393731
6257 230.2585092994045684017991
6259The principal branch of the Lambert W function has a rational
6260Taylor series expansion around `z = 0`::
6262 >>> nprint(taylor(lambertw, 0, 6), 10)
6263 [0.0, 1.0, -1.0, 1.5, -2.666666667, 5.208333333, -10.8]
6265Some special values and limits are::
6267 >>> lambertw(0)
6268 0.0
6269 >>> lambertw(1)
6270 0.5671432904097838729999687
6271 >>> lambertw(e)
6272 1.0
6273 >>> lambertw(inf)
6274 +inf
6275 >>> lambertw(0, k=-1)
6276 -inf
6277 >>> lambertw(0, k=3)
6278 -inf
6279 >>> lambertw(inf, k=2)
6280 (+inf + 12.56637061435917295385057j)
6281 >>> lambertw(inf, k=3)
6282 (+inf + 18.84955592153875943077586j)
6283 >>> lambertw(-inf, k=3)
6284 (+inf + 21.9911485751285526692385j)
6286The `k = 0` and `k = -1` branches join at `z = -1/e` where
6287`W(z) = -1` for both branches. Since `-1/e` can only be represented
6288approximately with binary floating-point numbers, evaluating the
6289Lambert W function at this point only gives `-1` approximately::
6291 >>> lambertw(-1/e, 0)
6292 -0.9999999999998371330228251
6293 >>> lambertw(-1/e, -1)
6294 -1.000000000000162866977175
6296If `-1/e` happens to round in the negative direction, there might be
6297a small imaginary part::
6299 >>> mp.dps = 15
6300 >>> lambertw(-1/e)
6301 (-1.0 + 8.22007971483662e-9j)
6302 >>> lambertw(-1/e+eps)
6303 -0.999999966242188
6305**References**
63071. [Corless]_
6308"""
6310barnesg = r"""
6311Evaluates the Barnes G-function, which generalizes the
6312superfactorial (:func:`~mpmath.superfac`) and by extension also the
6313hyperfactorial (:func:`~mpmath.hyperfac`) to the complex numbers
6314in an analogous way to how the gamma function generalizes
6315the ordinary factorial.
6317The Barnes G-function may be defined in terms of a Weierstrass
6318product:
6320.. math ::
6322 G(z+1) = (2\pi)^{z/2} e^{-[z(z+1)+\gamma z^2]/2}
6323 \prod_{n=1}^\infty
6324 \left[\left(1+\frac{z}{n}\right)^ne^{-z+z^2/(2n)}\right]
6326For positive integers `n`, we have have relation to superfactorials
6327`G(n) = \mathrm{sf}(n-2) = 0! \cdot 1! \cdots (n-2)!`.
6329**Examples**
6331Some elementary values and limits of the Barnes G-function::
6333 >>> from mpmath import *
6334 >>> mp.dps = 15; mp.pretty = True
6335 >>> barnesg(1), barnesg(2), barnesg(3)
6336 (1.0, 1.0, 1.0)
6337 >>> barnesg(4)
6338 2.0
6339 >>> barnesg(5)
6340 12.0
6341 >>> barnesg(6)
6342 288.0
6343 >>> barnesg(7)
6344 34560.0
6345 >>> barnesg(8)
6346 24883200.0
6347 >>> barnesg(inf)
6348 +inf
6349 >>> barnesg(0), barnesg(-1), barnesg(-2)
6350 (0.0, 0.0, 0.0)
6352Closed-form values are known for some rational arguments::
6354 >>> barnesg('1/2')
6355 0.603244281209446
6356 >>> sqrt(exp(0.25+log(2)/12)/sqrt(pi)/glaisher**3)
6357 0.603244281209446
6358 >>> barnesg('1/4')
6359 0.29375596533861
6360 >>> nthroot(exp('3/8')/exp(catalan/pi)/
6361 ... gamma(0.25)**3/sqrt(glaisher)**9, 4)
6362 0.29375596533861
6364The Barnes G-function satisfies the functional equation
6365`G(z+1) = \Gamma(z) G(z)`::
6367 >>> z = pi
6368 >>> barnesg(z+1)
6369 2.39292119327948
6370 >>> gamma(z)*barnesg(z)
6371 2.39292119327948
6373The asymptotic growth rate of the Barnes G-function is related to
6374the Glaisher-Kinkelin constant::
6376 >>> limit(lambda n: barnesg(n+1)/(n**(n**2/2-mpf(1)/12)*
6377 ... (2*pi)**(n/2)*exp(-3*n**2/4)), inf)
6378 0.847536694177301
6379 >>> exp('1/12')/glaisher
6380 0.847536694177301
6382The Barnes G-function can be differentiated in closed form::
6384 >>> z = 3
6385 >>> diff(barnesg, z)
6386 0.264507203401607
6387 >>> barnesg(z)*((z-1)*psi(0,z)-z+(log(2*pi)+1)/2)
6388 0.264507203401607
6390Evaluation is supported for arbitrary arguments and at arbitrary
6391precision::
6393 >>> barnesg(6.5)
6394 2548.7457695685
6395 >>> barnesg(-pi)
6396 0.00535976768353037
6397 >>> barnesg(3+4j)
6398 (-0.000676375932234244 - 4.42236140124728e-5j)
6399 >>> mp.dps = 50
6400 >>> barnesg(1/sqrt(2))
6401 0.81305501090451340843586085064413533788206204124732
6402 >>> q = barnesg(10j)
6403 >>> q.real
6404 0.000000000021852360840356557241543036724799812371995850552234
6405 >>> q.imag
6406 -0.00000000000070035335320062304849020654215545839053210041457588
6407 >>> mp.dps = 15
6408 >>> barnesg(100)
6409 3.10361006263698e+6626
6410 >>> barnesg(-101)
6411 0.0
6412 >>> barnesg(-10.5)
6413 5.94463017605008e+25
6414 >>> barnesg(-10000.5)
6415 -6.14322868174828e+167480422
6416 >>> barnesg(1000j)
6417 (5.21133054865546e-1173597 + 4.27461836811016e-1173597j)
6418 >>> barnesg(-1000+1000j)
6419 (2.43114569750291e+1026623 + 2.24851410674842e+1026623j)
6422**References**
64241. Whittaker & Watson, *A Course of Modern Analysis*,
6425 Cambridge University Press, 4th edition (1927), p.264
64262. http://en.wikipedia.org/wiki/Barnes_G-function
64273. http://mathworld.wolfram.com/BarnesG-Function.html
6429"""
6431superfac = r"""
6432Computes the superfactorial, defined as the product of
6433consecutive factorials
6435.. math ::
6437 \mathrm{sf}(n) = \prod_{k=1}^n k!
6439For general complex `z`, `\mathrm{sf}(z)` is defined
6440in terms of the Barnes G-function (see :func:`~mpmath.barnesg`).
6442**Examples**
6444The first few superfactorials are (OEIS A000178)::
6446 >>> from mpmath import *
6447 >>> mp.dps = 15; mp.pretty = True
6448 >>> for n in range(10):
6449 ... print("%s %s" % (n, superfac(n)))
6450 ...
6451 0 1.0
6452 1 1.0
6453 2 2.0
6454 3 12.0
6455 4 288.0
6456 5 34560.0
6457 6 24883200.0
6458 7 125411328000.0
6459 8 5.05658474496e+15
6460 9 1.83493347225108e+21
6462Superfactorials grow very rapidly::
6464 >>> superfac(1000)
6465 3.24570818422368e+1177245
6466 >>> superfac(10**10)
6467 2.61398543581249e+467427913956904067453
6469Evaluation is supported for arbitrary arguments::
6471 >>> mp.dps = 25
6472 >>> superfac(pi)
6473 17.20051550121297985285333
6474 >>> superfac(2+3j)
6475 (-0.005915485633199789627466468 + 0.008156449464604044948738263j)
6476 >>> diff(superfac, 1)
6477 0.2645072034016070205673056
6479**References**
64811. http://oeis.org/A000178
6483"""
6486hyperfac = r"""
6487Computes the hyperfactorial, defined for integers as the product
6489.. math ::
6491 H(n) = \prod_{k=1}^n k^k.
6494The hyperfactorial satisfies the recurrence formula `H(z) = z^z H(z-1)`.
6495It can be defined more generally in terms of the Barnes G-function (see
6496:func:`~mpmath.barnesg`) and the gamma function by the formula
6498.. math ::
6500 H(z) = \frac{\Gamma(z+1)^z}{G(z)}.
6502The extension to complex numbers can also be done via
6503the integral representation
6505.. math ::
6507 H(z) = (2\pi)^{-z/2} \exp \left[
6508 {z+1 \choose 2} + \int_0^z \log(t!)\,dt
6509 \right].
6511**Examples**
6513The rapidly-growing sequence of hyperfactorials begins
6514(OEIS A002109)::
6516 >>> from mpmath import *
6517 >>> mp.dps = 15; mp.pretty = True
6518 >>> for n in range(10):
6519 ... print("%s %s" % (n, hyperfac(n)))
6520 ...
6521 0 1.0
6522 1 1.0
6523 2 4.0
6524 3 108.0
6525 4 27648.0
6526 5 86400000.0
6527 6 4031078400000.0
6528 7 3.3197663987712e+18
6529 8 5.56964379417266e+25
6530 9 2.15779412229419e+34
6532Some even larger hyperfactorials are::
6534 >>> hyperfac(1000)
6535 5.46458120882585e+1392926
6536 >>> hyperfac(10**10)
6537 4.60408207642219e+489142638002418704309
6539The hyperfactorial can be evaluated for arbitrary arguments::
6541 >>> hyperfac(0.5)
6542 0.880449235173423
6543 >>> diff(hyperfac, 1)
6544 0.581061466795327
6545 >>> hyperfac(pi)
6546 205.211134637462
6547 >>> hyperfac(-10+1j)
6548 (3.01144471378225e+46 - 2.45285242480185e+46j)
6550The recurrence property of the hyperfactorial holds
6551generally::
6553 >>> z = 3-4*j
6554 >>> hyperfac(z)
6555 (-4.49795891462086e-7 - 6.33262283196162e-7j)
6556 >>> z**z * hyperfac(z-1)
6557 (-4.49795891462086e-7 - 6.33262283196162e-7j)
6558 >>> z = mpf(-0.6)
6559 >>> chop(z**z * hyperfac(z-1))
6560 1.28170142849352
6561 >>> hyperfac(z)
6562 1.28170142849352
6564The hyperfactorial may also be computed using the integral
6565definition::
6567 >>> z = 2.5
6568 >>> hyperfac(z)
6569 15.9842119922237
6570 >>> (2*pi)**(-z/2)*exp(binomial(z+1,2) +
6571 ... quad(lambda t: loggamma(t+1), [0, z]))
6572 15.9842119922237
6574:func:`~mpmath.hyperfac` supports arbitrary-precision evaluation::
6576 >>> mp.dps = 50
6577 >>> hyperfac(10)
6578 215779412229418562091680268288000000000000000.0
6579 >>> hyperfac(1/sqrt(2))
6580 0.89404818005227001975423476035729076375705084390942
6582**References**
65841. http://oeis.org/A002109
65852. http://mathworld.wolfram.com/Hyperfactorial.html
6587"""
6589rgamma = r"""
6590Computes the reciprocal of the gamma function, `1/\Gamma(z)`. This
6591function evaluates to zero at the poles
6592of the gamma function, `z = 0, -1, -2, \ldots`.
6594**Examples**
6596Basic examples::
6598 >>> from mpmath import *
6599 >>> mp.dps = 25; mp.pretty = True
6600 >>> rgamma(1)
6601 1.0
6602 >>> rgamma(4)
6603 0.1666666666666666666666667
6604 >>> rgamma(0); rgamma(-1)
6605 0.0
6606 0.0
6607 >>> rgamma(1000)
6608 2.485168143266784862783596e-2565
6609 >>> rgamma(inf)
6610 0.0
6612A definite integral that can be evaluated in terms of elementary
6613integrals::
6615 >>> quad(rgamma, [0,inf])
6616 2.807770242028519365221501
6617 >>> e + quad(lambda t: exp(-t)/(pi**2+log(t)**2), [0,inf])
6618 2.807770242028519365221501
6619"""
6621loggamma = r"""
6622Computes the principal branch of the log-gamma function,
6623`\ln \Gamma(z)`. Unlike `\ln(\Gamma(z))`, which has infinitely many
6624complex branch cuts, the principal log-gamma function only has a single
6625branch cut along the negative half-axis. The principal branch
6626continuously matches the asymptotic Stirling expansion
6628.. math ::
6630 \ln \Gamma(z) \sim \frac{\ln(2 \pi)}{2} +
6631 \left(z-\frac{1}{2}\right) \ln(z) - z + O(z^{-1}).
6633The real parts of both functions agree, but their imaginary
6634parts generally differ by `2 n \pi` for some `n \in \mathbb{Z}`.
6635They coincide for `z \in \mathbb{R}, z > 0`.
6637Computationally, it is advantageous to use :func:`~mpmath.loggamma`
6638instead of :func:`~mpmath.gamma` for extremely large arguments.
6640**Examples**
6642Comparing with `\ln(\Gamma(z))`::
6644 >>> from mpmath import *
6645 >>> mp.dps = 25; mp.pretty = True
6646 >>> loggamma('13.2'); log(gamma('13.2'))
6647 20.49400419456603678498394
6648 20.49400419456603678498394
6649 >>> loggamma(3+4j)
6650 (-1.756626784603784110530604 + 4.742664438034657928194889j)
6651 >>> log(gamma(3+4j))
6652 (-1.756626784603784110530604 - 1.540520869144928548730397j)
6653 >>> log(gamma(3+4j)) + 2*pi*j
6654 (-1.756626784603784110530604 + 4.742664438034657928194889j)
6656Note the imaginary parts for negative arguments::
6658 >>> loggamma(-0.5); loggamma(-1.5); loggamma(-2.5)
6659 (1.265512123484645396488946 - 3.141592653589793238462643j)
6660 (0.8600470153764810145109327 - 6.283185307179586476925287j)
6661 (-0.05624371649767405067259453 - 9.42477796076937971538793j)
6663Some special values::
6665 >>> loggamma(1); loggamma(2)
6666 0.0
6667 0.0
6668 >>> loggamma(3); +ln2
6669 0.6931471805599453094172321
6670 0.6931471805599453094172321
6671 >>> loggamma(3.5); log(15*sqrt(pi)/8)
6672 1.200973602347074224816022
6673 1.200973602347074224816022
6674 >>> loggamma(inf)
6675 +inf
6677Huge arguments are permitted::
6679 >>> loggamma('1e30')
6680 6.807755278982137052053974e+31
6681 >>> loggamma('1e300')
6682 6.897755278982137052053974e+302
6683 >>> loggamma('1e3000')
6684 6.906755278982137052053974e+3003
6685 >>> loggamma('1e100000000000000000000')
6686 2.302585092994045684007991e+100000000000000000020
6687 >>> loggamma('1e30j')
6688 (-1.570796326794896619231322e+30 + 6.807755278982137052053974e+31j)
6689 >>> loggamma('1e300j')
6690 (-1.570796326794896619231322e+300 + 6.897755278982137052053974e+302j)
6691 >>> loggamma('1e3000j')
6692 (-1.570796326794896619231322e+3000 + 6.906755278982137052053974e+3003j)
6694The log-gamma function can be integrated analytically
6695on any interval of unit length::
6697 >>> z = 0
6698 >>> quad(loggamma, [z,z+1]); log(2*pi)/2
6699 0.9189385332046727417803297
6700 0.9189385332046727417803297
6701 >>> z = 3+4j
6702 >>> quad(loggamma, [z,z+1]); (log(z)-1)*z + log(2*pi)/2
6703 (-0.9619286014994750641314421 + 5.219637303741238195688575j)
6704 (-0.9619286014994750641314421 + 5.219637303741238195688575j)
6706The derivatives of the log-gamma function are given by the
6707polygamma function (:func:`~mpmath.psi`)::
6709 >>> diff(loggamma, -4+3j); psi(0, -4+3j)
6710 (1.688493531222971393607153 + 2.554898911356806978892748j)
6711 (1.688493531222971393607153 + 2.554898911356806978892748j)
6712 >>> diff(loggamma, -4+3j, 2); psi(1, -4+3j)
6713 (-0.1539414829219882371561038 - 0.1020485197430267719746479j)
6714 (-0.1539414829219882371561038 - 0.1020485197430267719746479j)
6716The log-gamma function satisfies an additive form of the
6717recurrence relation for the ordinary gamma function::
6719 >>> z = 2+3j
6720 >>> loggamma(z); loggamma(z+1) - log(z)
6721 (-2.092851753092733349564189 + 2.302396543466867626153708j)
6722 (-2.092851753092733349564189 + 2.302396543466867626153708j)
6724"""
6726siegeltheta = r"""
6727Computes the Riemann-Siegel theta function,
6729.. math ::
6731 \theta(t) = \frac{
6732 \log\Gamma\left(\frac{1+2it}{4}\right) -
6733 \log\Gamma\left(\frac{1-2it}{4}\right)
6734 }{2i} - \frac{\log \pi}{2} t.
6736The Riemann-Siegel theta function is important in
6737providing the phase factor for the Z-function
6738(see :func:`~mpmath.siegelz`). Evaluation is supported for real and
6739complex arguments::
6741 >>> from mpmath import *
6742 >>> mp.dps = 25; mp.pretty = True
6743 >>> siegeltheta(0)
6744 0.0
6745 >>> siegeltheta(inf)
6746 +inf
6747 >>> siegeltheta(-inf)
6748 -inf
6749 >>> siegeltheta(1)
6750 -1.767547952812290388302216
6751 >>> siegeltheta(10+0.25j)
6752 (-3.068638039426838572528867 + 0.05804937947429712998395177j)
6754Arbitrary derivatives may be computed with derivative = k
6756 >>> siegeltheta(1234, derivative=2)
6757 0.0004051864079114053109473741
6758 >>> diff(siegeltheta, 1234, n=2)
6759 0.0004051864079114053109473741
6762The Riemann-Siegel theta function has odd symmetry around `t = 0`,
6763two local extreme points and three real roots including 0 (located
6764symmetrically)::
6766 >>> nprint(chop(taylor(siegeltheta, 0, 5)))
6767 [0.0, -2.68609, 0.0, 2.69433, 0.0, -6.40218]
6768 >>> findroot(diffun(siegeltheta), 7)
6769 6.28983598883690277966509
6770 >>> findroot(siegeltheta, 20)
6771 17.84559954041086081682634
6773For large `t`, there is a famous asymptotic formula
6774for `\theta(t)`, to first order given by::
6776 >>> t = mpf(10**6)
6777 >>> siegeltheta(t)
6778 5488816.353078403444882823
6779 >>> -t*log(2*pi/t)/2-t/2
6780 5488816.745777464310273645
6781"""
6783grampoint = r"""
6784Gives the `n`-th Gram point `g_n`, defined as the solution
6785to the equation `\theta(g_n) = \pi n` where `\theta(t)`
6786is the Riemann-Siegel theta function (:func:`~mpmath.siegeltheta`).
6788The first few Gram points are::
6790 >>> from mpmath import *
6791 >>> mp.dps = 25; mp.pretty = True
6792 >>> grampoint(0)
6793 17.84559954041086081682634
6794 >>> grampoint(1)
6795 23.17028270124630927899664
6796 >>> grampoint(2)
6797 27.67018221781633796093849
6798 >>> grampoint(3)
6799 31.71797995476405317955149
6801Checking the definition::
6803 >>> siegeltheta(grampoint(3))
6804 9.42477796076937971538793
6805 >>> 3*pi
6806 9.42477796076937971538793
6808A large Gram point::
6810 >>> grampoint(10**10)
6811 3293531632.728335454561153
6813Gram points are useful when studying the Z-function
6814(:func:`~mpmath.siegelz`). See the documentation of that function
6815for additional examples.
6817:func:`~mpmath.grampoint` can solve the defining equation for
6818nonintegral `n`. There is a fixed point where `g(x) = x`::
6820 >>> findroot(lambda x: grampoint(x) - x, 10000)
6821 9146.698193171459265866198
6823**References**
68251. http://mathworld.wolfram.com/GramPoint.html
6827"""
6829siegelz = r"""
6830Computes the Z-function, also known as the Riemann-Siegel Z function,
6832.. math ::
6834 Z(t) = e^{i \theta(t)} \zeta(1/2+it)
6836where `\zeta(s)` is the Riemann zeta function (:func:`~mpmath.zeta`)
6837and where `\theta(t)` denotes the Riemann-Siegel theta function
6838(see :func:`~mpmath.siegeltheta`).
6840Evaluation is supported for real and complex arguments::
6842 >>> from mpmath import *
6843 >>> mp.dps = 25; mp.pretty = True
6844 >>> siegelz(1)
6845 -0.7363054628673177346778998
6846 >>> siegelz(3+4j)
6847 (-0.1852895764366314976003936 - 0.2773099198055652246992479j)
6849The first four derivatives are supported, using the
6850optional *derivative* keyword argument::
6852 >>> siegelz(1234567, derivative=3)
6853 56.89689348495089294249178
6854 >>> diff(siegelz, 1234567, n=3)
6855 56.89689348495089294249178
6858The Z-function has a Maclaurin expansion::
6860 >>> nprint(chop(taylor(siegelz, 0, 4)))
6861 [-1.46035, 0.0, 2.73588, 0.0, -8.39357]
6863The Z-function `Z(t)` is equal to `\pm |\zeta(s)|` on the
6864critical line `s = 1/2+it` (i.e. for real arguments `t`
6865to `Z`). Its zeros coincide with those of the Riemann zeta
6866function::
6868 >>> findroot(siegelz, 14)
6869 14.13472514173469379045725
6870 >>> findroot(siegelz, 20)
6871 21.02203963877155499262848
6872 >>> findroot(zeta, 0.5+14j)
6873 (0.5 + 14.13472514173469379045725j)
6874 >>> findroot(zeta, 0.5+20j)
6875 (0.5 + 21.02203963877155499262848j)
6877Since the Z-function is real-valued on the critical line
6878(and unlike `|\zeta(s)|` analytic), it is useful for
6879investigating the zeros of the Riemann zeta function.
6880For example, one can use a root-finding algorithm based
6881on sign changes::
6883 >>> findroot(siegelz, [100, 200], solver='bisect')
6884 176.4414342977104188888926
6886To locate roots, Gram points `g_n` which can be computed
6887by :func:`~mpmath.grampoint` are useful. If `(-1)^n Z(g_n)` is
6888positive for two consecutive `n`, then `Z(t)` must have
6889a zero between those points::
6891 >>> g10 = grampoint(10)
6892 >>> g11 = grampoint(11)
6893 >>> (-1)**10 * siegelz(g10) > 0
6894 True
6895 >>> (-1)**11 * siegelz(g11) > 0
6896 True
6897 >>> findroot(siegelz, [g10, g11], solver='bisect')
6898 56.44624769706339480436776
6899 >>> g10, g11
6900 (54.67523744685325626632663, 57.54516517954725443703014)
6902"""
6904riemannr = r"""
6905Evaluates the Riemann R function, a smooth approximation of the
6906prime counting function `\pi(x)` (see :func:`~mpmath.primepi`). The Riemann
6907R function gives a fast numerical approximation useful e.g. to
6908roughly estimate the number of primes in a given interval.
6910The Riemann R function is computed using the rapidly convergent Gram
6911series,
6913.. math ::
6915 R(x) = 1 + \sum_{k=1}^{\infty}
6916 \frac{\log^k x}{k k! \zeta(k+1)}.
6918From the Gram series, one sees that the Riemann R function is a
6919well-defined analytic function (except for a branch cut along
6920the negative real half-axis); it can be evaluated for arbitrary
6921real or complex arguments.
6923The Riemann R function gives a very accurate approximation
6924of the prime counting function. For example, it is wrong by at
6925most 2 for `x < 1000`, and for `x = 10^9` differs from the exact
6926value of `\pi(x)` by 79, or less than two parts in a million.
6927It is about 10 times more accurate than the logarithmic integral
6928estimate (see :func:`~mpmath.li`), which however is even faster to evaluate.
6929It is orders of magnitude more accurate than the extremely
6930fast `x/\log x` estimate.
6932**Examples**
6934For small arguments, the Riemann R function almost exactly
6935gives the prime counting function if rounded to the nearest
6936integer::
6938 >>> from mpmath import *
6939 >>> mp.dps = 15; mp.pretty = True
6940 >>> primepi(50), riemannr(50)
6941 (15, 14.9757023241462)
6942 >>> max(abs(primepi(n)-int(round(riemannr(n)))) for n in range(100))
6943 1
6944 >>> max(abs(primepi(n)-int(round(riemannr(n)))) for n in range(300))
6945 2
6947The Riemann R function can be evaluated for arguments far too large
6948for exact determination of `\pi(x)` to be computationally
6949feasible with any presently known algorithm::
6951 >>> riemannr(10**30)
6952 1.46923988977204e+28
6953 >>> riemannr(10**100)
6954 4.3619719871407e+97
6955 >>> riemannr(10**1000)
6956 4.3448325764012e+996
6958A comparison of the Riemann R function and logarithmic integral estimates
6959for `\pi(x)` using exact values of `\pi(10^n)` up to `n = 9`.
6960The fractional error is shown in parentheses::
6962 >>> exact = [4,25,168,1229,9592,78498,664579,5761455,50847534]
6963 >>> for n, p in enumerate(exact):
6964 ... n += 1
6965 ... r, l = riemannr(10**n), li(10**n)
6966 ... rerr, lerr = nstr((r-p)/p,3), nstr((l-p)/p,3)
6967 ... print("%i %i %s(%s) %s(%s)" % (n, p, r, rerr, l, lerr))
6968 ...
6969 1 4 4.56458314100509(0.141) 6.1655995047873(0.541)
6970 2 25 25.6616332669242(0.0265) 30.1261415840796(0.205)
6971 3 168 168.359446281167(0.00214) 177.609657990152(0.0572)
6972 4 1229 1226.93121834343(-0.00168) 1246.13721589939(0.0139)
6973 5 9592 9587.43173884197(-0.000476) 9629.8090010508(0.00394)
6974 6 78498 78527.3994291277(0.000375) 78627.5491594622(0.00165)
6975 7 664579 664667.447564748(0.000133) 664918.405048569(0.000511)
6976 8 5761455 5761551.86732017(1.68e-5) 5762209.37544803(0.000131)
6977 9 50847534 50847455.4277214(-1.55e-6) 50849234.9570018(3.35e-5)
6979The derivative of the Riemann R function gives the approximate
6980probability for a number of magnitude `x` to be prime::
6982 >>> diff(riemannr, 1000)
6983 0.141903028110784
6984 >>> mpf(primepi(1050) - primepi(950)) / 100
6985 0.15
6987Evaluation is supported for arbitrary arguments and at arbitrary
6988precision::
6990 >>> mp.dps = 30
6991 >>> riemannr(7.5)
6992 3.72934743264966261918857135136
6993 >>> riemannr(-4+2j)
6994 (-0.551002208155486427591793957644 + 2.16966398138119450043195899746j)
6996"""
6998primepi = r"""
6999Evaluates the prime counting function, `\pi(x)`, which gives
7000the number of primes less than or equal to `x`. The argument
7001`x` may be fractional.
7003The prime counting function is very expensive to evaluate
7004precisely for large `x`, and the present implementation is
7005not optimized in any way. For numerical approximation of the
7006prime counting function, it is better to use :func:`~mpmath.primepi2`
7007or :func:`~mpmath.riemannr`.
7009Some values of the prime counting function::
7011 >>> from mpmath import *
7012 >>> [primepi(k) for k in range(20)]
7013 [0, 0, 1, 2, 2, 3, 3, 4, 4, 4, 4, 5, 5, 6, 6, 6, 6, 7, 7, 8]
7014 >>> primepi(3.5)
7015 2
7016 >>> primepi(100000)
7017 9592
7019"""
7021primepi2 = r"""
7022Returns an interval (as an ``mpi`` instance) providing bounds
7023for the value of the prime counting function `\pi(x)`. For small
7024`x`, :func:`~mpmath.primepi2` returns an exact interval based on
7025the output of :func:`~mpmath.primepi`. For `x > 2656`, a loose interval
7026based on Schoenfeld's inequality
7028.. math ::
7030 |\pi(x) - \mathrm{li}(x)| < \frac{\sqrt x \log x}{8 \pi}
7032is returned. This estimate is rigorous assuming the truth of
7033the Riemann hypothesis, and can be computed very quickly.
7035**Examples**
7037Exact values of the prime counting function for small `x`::
7039 >>> from mpmath import *
7040 >>> mp.dps = 15; mp.pretty = True
7041 >>> iv.dps = 15; iv.pretty = True
7042 >>> primepi2(10)
7043 [4.0, 4.0]
7044 >>> primepi2(100)
7045 [25.0, 25.0]
7046 >>> primepi2(1000)
7047 [168.0, 168.0]
7049Loose intervals are generated for moderately large `x`:
7051 >>> primepi2(10000), primepi(10000)
7052 ([1209.0, 1283.0], 1229)
7053 >>> primepi2(50000), primepi(50000)
7054 ([5070.0, 5263.0], 5133)
7056As `x` increases, the absolute error gets worse while the relative
7057error improves. The exact value of `\pi(10^{23})` is
70581925320391606803968923, and :func:`~mpmath.primepi2` gives 9 significant
7059digits::
7061 >>> p = primepi2(10**23)
7062 >>> p
7063 [1.9253203909477020467e+21, 1.925320392280406229e+21]
7064 >>> mpf(p.delta) / mpf(p.a)
7065 6.9219865355293e-10
7067A more precise, nonrigorous estimate for `\pi(x)` can be
7068obtained using the Riemann R function (:func:`~mpmath.riemannr`).
7069For large enough `x`, the value returned by :func:`~mpmath.primepi2`
7070essentially amounts to a small perturbation of the value returned by
7071:func:`~mpmath.riemannr`::
7073 >>> primepi2(10**100)
7074 [4.3619719871407024816e+97, 4.3619719871407032404e+97]
7075 >>> riemannr(10**100)
7076 4.3619719871407e+97
7077"""
7079primezeta = r"""
7080Computes the prime zeta function, which is defined
7081in analogy with the Riemann zeta function (:func:`~mpmath.zeta`)
7082as
7084.. math ::
7086 P(s) = \sum_p \frac{1}{p^s}
7088where the sum is taken over all prime numbers `p`. Although
7089this sum only converges for `\mathrm{Re}(s) > 1`, the
7090function is defined by analytic continuation in the
7091half-plane `\mathrm{Re}(s) > 0`.
7093**Examples**
7095Arbitrary-precision evaluation for real and complex arguments is
7096supported::
7098 >>> from mpmath import *
7099 >>> mp.dps = 30; mp.pretty = True
7100 >>> primezeta(2)
7101 0.452247420041065498506543364832
7102 >>> primezeta(pi)
7103 0.15483752698840284272036497397
7104 >>> mp.dps = 50
7105 >>> primezeta(3)
7106 0.17476263929944353642311331466570670097541212192615
7107 >>> mp.dps = 20
7108 >>> primezeta(3+4j)
7109 (-0.12085382601645763295 - 0.013370403397787023602j)
7111The prime zeta function has a logarithmic pole at `s = 1`,
7112with residue equal to the difference of the Mertens and
7113Euler constants::
7115 >>> primezeta(1)
7116 +inf
7117 >>> extradps(25)(lambda x: primezeta(1+x)+log(x))(+eps)
7118 -0.31571845205389007685
7119 >>> mertens-euler
7120 -0.31571845205389007685
7122The analytic continuation to `0 < \mathrm{Re}(s) \le 1`
7123is implemented. In this strip the function exhibits
7124very complex behavior; on the unit interval, it has poles at
7125`1/n` for every squarefree integer `n`::
7127 >>> primezeta(0.5) # Pole at s = 1/2
7128 (-inf + 3.1415926535897932385j)
7129 >>> primezeta(0.25)
7130 (-1.0416106801757269036 + 0.52359877559829887308j)
7131 >>> primezeta(0.5+10j)
7132 (0.54892423556409790529 + 0.45626803423487934264j)
7134Although evaluation works in principle for any `\mathrm{Re}(s) > 0`,
7135it should be noted that the evaluation time increases exponentially
7136as `s` approaches the imaginary axis.
7138For large `\mathrm{Re}(s)`, `P(s)` is asymptotic to `2^{-s}`::
7140 >>> primezeta(inf)
7141 0.0
7142 >>> primezeta(10), mpf(2)**-10
7143 (0.00099360357443698021786, 0.0009765625)
7144 >>> primezeta(1000)
7145 9.3326361850321887899e-302
7146 >>> primezeta(1000+1000j)
7147 (-3.8565440833654995949e-302 - 8.4985390447553234305e-302j)
7149**References**
7151Carl-Erik Froberg, "On the prime zeta function",
7152BIT 8 (1968), pp. 187-202.
7154"""
7156bernpoly = r"""
7157Evaluates the Bernoulli polynomial `B_n(z)`.
7159The first few Bernoulli polynomials are::
7161 >>> from mpmath import *
7162 >>> mp.dps = 15; mp.pretty = True
7163 >>> for n in range(6):
7164 ... nprint(chop(taylor(lambda x: bernpoly(n,x), 0, n)))
7165 ...
7166 [1.0]
7167 [-0.5, 1.0]
7168 [0.166667, -1.0, 1.0]
7169 [0.0, 0.5, -1.5, 1.0]
7170 [-0.0333333, 0.0, 1.0, -2.0, 1.0]
7171 [0.0, -0.166667, 0.0, 1.66667, -2.5, 1.0]
7173At `z = 0`, the Bernoulli polynomial evaluates to a
7174Bernoulli number (see :func:`~mpmath.bernoulli`)::
7176 >>> bernpoly(12, 0), bernoulli(12)
7177 (-0.253113553113553, -0.253113553113553)
7178 >>> bernpoly(13, 0), bernoulli(13)
7179 (0.0, 0.0)
7181Evaluation is accurate for large `n` and small `z`::
7183 >>> mp.dps = 25
7184 >>> bernpoly(100, 0.5)
7185 2.838224957069370695926416e+78
7186 >>> bernpoly(1000, 10.5)
7187 5.318704469415522036482914e+1769
7189"""
7191polylog = r"""
7192Computes the polylogarithm, defined by the sum
7194.. math ::
7196 \mathrm{Li}_s(z) = \sum_{k=1}^{\infty} \frac{z^k}{k^s}.
7198This series is convergent only for `|z| < 1`, so elsewhere
7199the analytic continuation is implied.
7201The polylogarithm should not be confused with the logarithmic
7202integral (also denoted by Li or li), which is implemented
7203as :func:`~mpmath.li`.
7205**Examples**
7207The polylogarithm satisfies a huge number of functional identities.
7208A sample of polylogarithm evaluations is shown below::
7210 >>> from mpmath import *
7211 >>> mp.dps = 15; mp.pretty = True
7212 >>> polylog(1,0.5), log(2)
7213 (0.693147180559945, 0.693147180559945)
7214 >>> polylog(2,0.5), (pi**2-6*log(2)**2)/12
7215 (0.582240526465012, 0.582240526465012)
7216 >>> polylog(2,-phi), -log(phi)**2-pi**2/10
7217 (-1.21852526068613, -1.21852526068613)
7218 >>> polylog(3,0.5), 7*zeta(3)/8-pi**2*log(2)/12+log(2)**3/6
7219 (0.53721319360804, 0.53721319360804)
7221:func:`~mpmath.polylog` can evaluate the analytic continuation of the
7222polylogarithm when `s` is an integer::
7224 >>> polylog(2, 10)
7225 (0.536301287357863 - 7.23378441241546j)
7226 >>> polylog(2, -10)
7227 -4.1982778868581
7228 >>> polylog(2, 10j)
7229 (-3.05968879432873 + 3.71678149306807j)
7230 >>> polylog(-2, 10)
7231 -0.150891632373114
7232 >>> polylog(-2, -10)
7233 0.067618332081142
7234 >>> polylog(-2, 10j)
7235 (0.0384353698579347 + 0.0912451798066779j)
7237Some more examples, with arguments on the unit circle (note that
7238the series definition cannot be used for computation here)::
7240 >>> polylog(2,j)
7241 (-0.205616758356028 + 0.915965594177219j)
7242 >>> j*catalan-pi**2/48
7243 (-0.205616758356028 + 0.915965594177219j)
7244 >>> polylog(3,exp(2*pi*j/3))
7245 (-0.534247512515375 + 0.765587078525922j)
7246 >>> -4*zeta(3)/9 + 2*j*pi**3/81
7247 (-0.534247512515375 + 0.765587078525921j)
7249Polylogarithms of different order are related by integration
7250and differentiation::
7252 >>> s, z = 3, 0.5
7253 >>> polylog(s+1, z)
7254 0.517479061673899
7255 >>> quad(lambda t: polylog(s,t)/t, [0, z])
7256 0.517479061673899
7257 >>> z*diff(lambda t: polylog(s+2,t), z)
7258 0.517479061673899
7260Taylor series expansions around `z = 0` are::
7262 >>> for n in range(-3, 4):
7263 ... nprint(taylor(lambda x: polylog(n,x), 0, 5))
7264 ...
7265 [0.0, 1.0, 8.0, 27.0, 64.0, 125.0]
7266 [0.0, 1.0, 4.0, 9.0, 16.0, 25.0]
7267 [0.0, 1.0, 2.0, 3.0, 4.0, 5.0]
7268 [0.0, 1.0, 1.0, 1.0, 1.0, 1.0]
7269 [0.0, 1.0, 0.5, 0.333333, 0.25, 0.2]
7270 [0.0, 1.0, 0.25, 0.111111, 0.0625, 0.04]
7271 [0.0, 1.0, 0.125, 0.037037, 0.015625, 0.008]
7273The series defining the polylogarithm is simultaneously
7274a Taylor series and an L-series. For certain values of `z`, the
7275polylogarithm reduces to a pure zeta function::
7277 >>> polylog(pi, 1), zeta(pi)
7278 (1.17624173838258, 1.17624173838258)
7279 >>> polylog(pi, -1), -altzeta(pi)
7280 (-0.909670702980385, -0.909670702980385)
7282Evaluation for arbitrary, nonintegral `s` is supported
7283for `z` within the unit circle:
7285 >>> polylog(3+4j, 0.25)
7286 (0.24258605789446 - 0.00222938275488344j)
7287 >>> nsum(lambda k: 0.25**k / k**(3+4j), [1,inf])
7288 (0.24258605789446 - 0.00222938275488344j)
7290It is also supported outside of the unit circle::
7292 >>> polylog(1+j, 20+40j)
7293 (-7.1421172179728 - 3.92726697721369j)
7294 >>> polylog(1+j, 200+400j)
7295 (-5.41934747194626 - 9.94037752563927j)
7297**References**
72991. Richard Crandall, "Note on fast polylogarithm computation"
7300 http://www.reed.edu/physics/faculty/crandall/papers/Polylog.pdf
73012. http://en.wikipedia.org/wiki/Polylogarithm
73023. http://mathworld.wolfram.com/Polylogarithm.html
7304"""
7306bell = r"""
7307For `n` a nonnegative integer, ``bell(n,x)`` evaluates the Bell
7308polynomial `B_n(x)`, the first few of which are
7310.. math ::
7312 B_0(x) = 1
7314 B_1(x) = x
7316 B_2(x) = x^2+x
7318 B_3(x) = x^3+3x^2+x
7320If `x = 1` or :func:`~mpmath.bell` is called with only one argument, it
7321gives the `n`-th Bell number `B_n`, which is the number of
7322partitions of a set with `n` elements. By setting the precision to
7323at least `\log_{10} B_n` digits, :func:`~mpmath.bell` provides fast
7324calculation of exact Bell numbers.
7326In general, :func:`~mpmath.bell` computes
7328.. math ::
7330 B_n(x) = e^{-x} \left(\mathrm{sinc}(\pi n) + E_n(x)\right)
7332where `E_n(x)` is the generalized exponential function implemented
7333by :func:`~mpmath.polyexp`. This is an extension of Dobinski's formula [1],
7334where the modification is the sinc term ensuring that `B_n(x)` is
7335continuous in `n`; :func:`~mpmath.bell` can thus be evaluated,
7336differentiated, etc for arbitrary complex arguments.
7338**Examples**
7340Simple evaluations::
7342 >>> from mpmath import *
7343 >>> mp.dps = 25; mp.pretty = True
7344 >>> bell(0, 2.5)
7345 1.0
7346 >>> bell(1, 2.5)
7347 2.5
7348 >>> bell(2, 2.5)
7349 8.75
7351Evaluation for arbitrary complex arguments::
7353 >>> bell(5.75+1j, 2-3j)
7354 (-10767.71345136587098445143 - 15449.55065599872579097221j)
7356The first few Bell polynomials::
7358 >>> for k in range(7):
7359 ... nprint(taylor(lambda x: bell(k,x), 0, k))
7360 ...
7361 [1.0]
7362 [0.0, 1.0]
7363 [0.0, 1.0, 1.0]
7364 [0.0, 1.0, 3.0, 1.0]
7365 [0.0, 1.0, 7.0, 6.0, 1.0]
7366 [0.0, 1.0, 15.0, 25.0, 10.0, 1.0]
7367 [0.0, 1.0, 31.0, 90.0, 65.0, 15.0, 1.0]
7369The first few Bell numbers and complementary Bell numbers::
7371 >>> [int(bell(k)) for k in range(10)]
7372 [1, 1, 2, 5, 15, 52, 203, 877, 4140, 21147]
7373 >>> [int(bell(k,-1)) for k in range(10)]
7374 [1, -1, 0, 1, 1, -2, -9, -9, 50, 267]
7376Large Bell numbers::
7378 >>> mp.dps = 50
7379 >>> bell(50)
7380 185724268771078270438257767181908917499221852770.0
7381 >>> bell(50,-1)
7382 -29113173035759403920216141265491160286912.0
7384Some even larger values::
7386 >>> mp.dps = 25
7387 >>> bell(1000,-1)
7388 -1.237132026969293954162816e+1869
7389 >>> bell(1000)
7390 2.989901335682408421480422e+1927
7391 >>> bell(1000,2)
7392 6.591553486811969380442171e+1987
7393 >>> bell(1000,100.5)
7394 9.101014101401543575679639e+2529
7396A determinant identity satisfied by Bell numbers::
7398 >>> mp.dps = 15
7399 >>> N = 8
7400 >>> det([[bell(k+j) for j in range(N)] for k in range(N)])
7401 125411328000.0
7402 >>> superfac(N-1)
7403 125411328000.0
7405**References**
74071. http://mathworld.wolfram.com/DobinskisFormula.html
7409"""
7411polyexp = r"""
7412Evaluates the polyexponential function, defined for arbitrary
7413complex `s`, `z` by the series
7415.. math ::
7417 E_s(z) = \sum_{k=1}^{\infty} \frac{k^s}{k!} z^k.
7419`E_s(z)` is constructed from the exponential function analogously
7420to how the polylogarithm is constructed from the ordinary
7421logarithm; as a function of `s` (with `z` fixed), `E_s` is an L-series
7422It is an entire function of both `s` and `z`.
7424The polyexponential function provides a generalization of the
7425Bell polynomials `B_n(x)` (see :func:`~mpmath.bell`) to noninteger orders `n`.
7426In terms of the Bell polynomials,
7428.. math ::
7430 E_s(z) = e^z B_s(z) - \mathrm{sinc}(\pi s).
7432Note that `B_n(x)` and `e^{-x} E_n(x)` are identical if `n`
7433is a nonzero integer, but not otherwise. In particular, they differ
7434at `n = 0`.
7436**Examples**
7438Evaluating a series::
7440 >>> from mpmath import *
7441 >>> mp.dps = 25; mp.pretty = True
7442 >>> nsum(lambda k: sqrt(k)/fac(k), [1,inf])
7443 2.101755547733791780315904
7444 >>> polyexp(0.5,1)
7445 2.101755547733791780315904
7447Evaluation for arbitrary arguments::
7449 >>> polyexp(-3-4j, 2.5+2j)
7450 (2.351660261190434618268706 + 1.202966666673054671364215j)
7452Evaluation is accurate for tiny function values::
7454 >>> polyexp(4, -100)
7455 3.499471750566824369520223e-36
7457If `n` is a nonpositive integer, `E_n` reduces to a special
7458instance of the hypergeometric function `\,_pF_q`::
7460 >>> n = 3
7461 >>> x = pi
7462 >>> polyexp(-n,x)
7463 4.042192318847986561771779
7464 >>> x*hyper([1]*(n+1), [2]*(n+1), x)
7465 4.042192318847986561771779
7467"""
7469cyclotomic = r"""
7470Evaluates the cyclotomic polynomial `\Phi_n(x)`, defined by
7472.. math ::
7474 \Phi_n(x) = \prod_{\zeta} (x - \zeta)
7476where `\zeta` ranges over all primitive `n`-th roots of unity
7477(see :func:`~mpmath.unitroots`). An equivalent representation, used
7478for computation, is
7480.. math ::
7482 \Phi_n(x) = \prod_{d\mid n}(x^d-1)^{\mu(n/d)} = \Phi_n(x)
7484where `\mu(m)` denotes the Moebius function. The cyclotomic
7485polynomials are integer polynomials, the first of which can be
7486written explicitly as
7488.. math ::
7490 \Phi_0(x) = 1
7492 \Phi_1(x) = x - 1
7494 \Phi_2(x) = x + 1
7496 \Phi_3(x) = x^3 + x^2 + 1
7498 \Phi_4(x) = x^2 + 1
7500 \Phi_5(x) = x^4 + x^3 + x^2 + x + 1
7502 \Phi_6(x) = x^2 - x + 1
7504**Examples**
7506The coefficients of low-order cyclotomic polynomials can be recovered
7507using Taylor expansion::
7509 >>> from mpmath import *
7510 >>> mp.dps = 15; mp.pretty = True
7511 >>> for n in range(9):
7512 ... p = chop(taylor(lambda x: cyclotomic(n,x), 0, 10))
7513 ... print("%s %s" % (n, nstr(p[:10+1-p[::-1].index(1)])))
7514 ...
7515 0 [1.0]
7516 1 [-1.0, 1.0]
7517 2 [1.0, 1.0]
7518 3 [1.0, 1.0, 1.0]
7519 4 [1.0, 0.0, 1.0]
7520 5 [1.0, 1.0, 1.0, 1.0, 1.0]
7521 6 [1.0, -1.0, 1.0]
7522 7 [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
7523 8 [1.0, 0.0, 0.0, 0.0, 1.0]
7525The definition as a product over primitive roots may be checked
7526by computing the product explicitly (for a real argument, this
7527method will generally introduce numerical noise in the imaginary
7528part)::
7530 >>> mp.dps = 25
7531 >>> z = 3+4j
7532 >>> cyclotomic(10, z)
7533 (-419.0 - 360.0j)
7534 >>> fprod(z-r for r in unitroots(10, primitive=True))
7535 (-419.0 - 360.0j)
7536 >>> z = 3
7537 >>> cyclotomic(10, z)
7538 61.0
7539 >>> fprod(z-r for r in unitroots(10, primitive=True))
7540 (61.0 - 3.146045605088568607055454e-25j)
7542Up to permutation, the roots of a given cyclotomic polynomial
7543can be checked to agree with the list of primitive roots::
7545 >>> p = taylor(lambda x: cyclotomic(6,x), 0, 6)[:3]
7546 >>> for r in polyroots(p[::-1]):
7547 ... print(r)
7548 ...
7549 (0.5 - 0.8660254037844386467637232j)
7550 (0.5 + 0.8660254037844386467637232j)
7551 >>>
7552 >>> for r in unitroots(6, primitive=True):
7553 ... print(r)
7554 ...
7555 (0.5 + 0.8660254037844386467637232j)
7556 (0.5 - 0.8660254037844386467637232j)
7558"""
7560meijerg = r"""
7561Evaluates the Meijer G-function, defined as
7563.. math ::
7565 G^{m,n}_{p,q} \left( \left. \begin{matrix}
7566 a_1, \dots, a_n ; a_{n+1} \dots a_p \\
7567 b_1, \dots, b_m ; b_{m+1} \dots b_q
7568 \end{matrix}\; \right| \; z ; r \right) =
7569 \frac{1}{2 \pi i} \int_L
7570 \frac{\prod_{j=1}^m \Gamma(b_j+s) \prod_{j=1}^n\Gamma(1-a_j-s)}
7571 {\prod_{j=n+1}^{p}\Gamma(a_j+s) \prod_{j=m+1}^q \Gamma(1-b_j-s)}
7572 z^{-s/r} ds
7574for an appropriate choice of the contour `L` (see references).
7576There are `p` elements `a_j`.
7577The argument *a_s* should be a pair of lists, the first containing the
7578`n` elements `a_1, \ldots, a_n` and the second containing
7579the `p-n` elements `a_{n+1}, \ldots a_p`.
7581There are `q` elements `b_j`.
7582The argument *b_s* should be a pair of lists, the first containing the
7583`m` elements `b_1, \ldots, b_m` and the second containing
7584the `q-m` elements `b_{m+1}, \ldots b_q`.
7586The implicit tuple `(m, n, p, q)` constitutes the order or degree of the
7587Meijer G-function, and is determined by the lengths of the coefficient
7588vectors. Confusingly, the indices in this tuple appear in a different order
7589from the coefficients, but this notation is standard. The many examples
7590given below should hopefully clear up any potential confusion.
7592**Algorithm**
7594The Meijer G-function is evaluated as a combination of hypergeometric series.
7595There are two versions of the function, which can be selected with
7596the optional *series* argument.
7598*series=1* uses a sum of `m` `\,_pF_{q-1}` functions of `z`
7600*series=2* uses a sum of `n` `\,_qF_{p-1}` functions of `1/z`
7602The default series is chosen based on the degree and `|z|` in order
7603to be consistent with Mathematica's. This definition of the Meijer G-function
7604has a discontinuity at `|z| = 1` for some orders, which can
7605be avoided by explicitly specifying a series.
7607Keyword arguments are forwarded to :func:`~mpmath.hypercomb`.
7609**Examples**
7611Many standard functions are special cases of the Meijer G-function
7612(possibly rescaled and/or with branch cut corrections). We define
7613some test parameters::
7615 >>> from mpmath import *
7616 >>> mp.dps = 25; mp.pretty = True
7617 >>> a = mpf(0.75)
7618 >>> b = mpf(1.5)
7619 >>> z = mpf(2.25)
7621The exponential function:
7622`e^z = G^{1,0}_{0,1} \left( \left. \begin{matrix} - \\ 0 \end{matrix} \;
7623\right| \; -z \right)`
7625 >>> meijerg([[],[]], [[0],[]], -z)
7626 9.487735836358525720550369
7627 >>> exp(z)
7628 9.487735836358525720550369
7630The natural logarithm:
7631`\log(1+z) = G^{1,2}_{2,2} \left( \left. \begin{matrix} 1, 1 \\ 1, 0
7632\end{matrix} \; \right| \; -z \right)`
7634 >>> meijerg([[1,1],[]], [[1],[0]], z)
7635 1.178654996341646117219023
7636 >>> log(1+z)
7637 1.178654996341646117219023
7639A rational function:
7640`\frac{z}{z+1} = G^{1,2}_{2,2} \left( \left. \begin{matrix} 1, 1 \\ 1, 1
7641\end{matrix} \; \right| \; z \right)`
7643 >>> meijerg([[1,1],[]], [[1],[1]], z)
7644 0.6923076923076923076923077
7645 >>> z/(z+1)
7646 0.6923076923076923076923077
7648The sine and cosine functions:
7650`\frac{1}{\sqrt \pi} \sin(2 \sqrt z) = G^{1,0}_{0,2} \left( \left. \begin{matrix}
7651- \\ \frac{1}{2}, 0 \end{matrix} \; \right| \; z \right)`
7653`\frac{1}{\sqrt \pi} \cos(2 \sqrt z) = G^{1,0}_{0,2} \left( \left. \begin{matrix}
7654- \\ 0, \frac{1}{2} \end{matrix} \; \right| \; z \right)`
7656 >>> meijerg([[],[]], [[0.5],[0]], (z/2)**2)
7657 0.4389807929218676682296453
7658 >>> sin(z)/sqrt(pi)
7659 0.4389807929218676682296453
7660 >>> meijerg([[],[]], [[0],[0.5]], (z/2)**2)
7661 -0.3544090145996275423331762
7662 >>> cos(z)/sqrt(pi)
7663 -0.3544090145996275423331762
7665Bessel functions:
7667`J_a(2 \sqrt z) = G^{1,0}_{0,2} \left( \left.
7668\begin{matrix} - \\ \frac{a}{2}, -\frac{a}{2}
7669\end{matrix} \; \right| \; z \right)`
7671`Y_a(2 \sqrt z) = G^{2,0}_{1,3} \left( \left.
7672\begin{matrix} \frac{-a-1}{2} \\ \frac{a}{2}, -\frac{a}{2}, \frac{-a-1}{2}
7673\end{matrix} \; \right| \; z \right)`
7675`(-z)^{a/2} z^{-a/2} I_a(2 \sqrt z) = G^{1,0}_{0,2} \left( \left.
7676\begin{matrix} - \\ \frac{a}{2}, -\frac{a}{2}
7677\end{matrix} \; \right| \; -z \right)`
7679`2 K_a(2 \sqrt z) = G^{2,0}_{0,2} \left( \left.
7680\begin{matrix} - \\ \frac{a}{2}, -\frac{a}{2}
7681\end{matrix} \; \right| \; z \right)`
7683As the example with the Bessel *I* function shows, a branch
7684factor is required for some arguments when inverting the square root.
7686 >>> meijerg([[],[]], [[a/2],[-a/2]], (z/2)**2)
7687 0.5059425789597154858527264
7688 >>> besselj(a,z)
7689 0.5059425789597154858527264
7690 >>> meijerg([[],[(-a-1)/2]], [[a/2,-a/2],[(-a-1)/2]], (z/2)**2)
7691 0.1853868950066556941442559
7692 >>> bessely(a, z)
7693 0.1853868950066556941442559
7694 >>> meijerg([[],[]], [[a/2],[-a/2]], -(z/2)**2)
7695 (0.8685913322427653875717476 + 2.096964974460199200551738j)
7696 >>> (-z)**(a/2) / z**(a/2) * besseli(a, z)
7697 (0.8685913322427653875717476 + 2.096964974460199200551738j)
7698 >>> 0.5*meijerg([[],[]], [[a/2,-a/2],[]], (z/2)**2)
7699 0.09334163695597828403796071
7700 >>> besselk(a,z)
7701 0.09334163695597828403796071
7703Error functions:
7705`\sqrt{\pi} z^{2(a-1)} \mathrm{erfc}(z) = G^{2,0}_{1,2} \left( \left.
7706\begin{matrix} a \\ a-1, a-\frac{1}{2}
7707\end{matrix} \; \right| \; z, \frac{1}{2} \right)`
7709 >>> meijerg([[],[a]], [[a-1,a-0.5],[]], z, 0.5)
7710 0.00172839843123091957468712
7711 >>> sqrt(pi) * z**(2*a-2) * erfc(z)
7712 0.00172839843123091957468712
7714A Meijer G-function of higher degree, (1,1,2,3):
7716 >>> meijerg([[a],[b]], [[a],[b,a-1]], z)
7717 1.55984467443050210115617
7718 >>> sin((b-a)*pi)/pi*(exp(z)-1)*z**(a-1)
7719 1.55984467443050210115617
7721A Meijer G-function of still higher degree, (4,1,2,4), that can
7722be expanded as a messy combination of exponential integrals:
7724 >>> meijerg([[a],[2*b-a]], [[b,a,b-0.5,-1-a+2*b],[]], z)
7725 0.3323667133658557271898061
7726 >>> chop(4**(a-b+1)*sqrt(pi)*gamma(2*b-2*a)*z**a*\
7727 ... expint(2*b-2*a, -2*sqrt(-z))*expint(2*b-2*a, 2*sqrt(-z)))
7728 0.3323667133658557271898061
7730In the following case, different series give different values::
7732 >>> chop(meijerg([[1],[0.25]],[[3],[0.5]],-2))
7733 -0.06417628097442437076207337
7734 >>> meijerg([[1],[0.25]],[[3],[0.5]],-2,series=1)
7735 0.1428699426155117511873047
7736 >>> chop(meijerg([[1],[0.25]],[[3],[0.5]],-2,series=2))
7737 -0.06417628097442437076207337
7739**References**
77411. http://en.wikipedia.org/wiki/Meijer_G-function
77432. http://mathworld.wolfram.com/MeijerG-Function.html
77453. http://functions.wolfram.com/HypergeometricFunctions/MeijerG/
77474. http://functions.wolfram.com/HypergeometricFunctions/MeijerG1/
7749"""
7751clsin = r"""
7752Computes the Clausen sine function, defined formally by the series
7754.. math ::
7756 \mathrm{Cl}_s(z) = \sum_{k=1}^{\infty} \frac{\sin(kz)}{k^s}.
7758The special case `\mathrm{Cl}_2(z)` (i.e. ``clsin(2,z)``) is the classical
7759"Clausen function". More generally, the Clausen function is defined for
7760complex `s` and `z`, even when the series does not converge. The
7761Clausen function is related to the polylogarithm (:func:`~mpmath.polylog`) as
7763.. math ::
7765 \mathrm{Cl}_s(z) = \frac{1}{2i}\left(\mathrm{Li}_s\left(e^{iz}\right) -
7766 \mathrm{Li}_s\left(e^{-iz}\right)\right)
7768 = \mathrm{Im}\left[\mathrm{Li}_s(e^{iz})\right] \quad (s, z \in \mathbb{R}),
7770and this representation can be taken to provide the analytic continuation of the
7771series. The complementary function :func:`~mpmath.clcos` gives the corresponding
7772cosine sum.
7774**Examples**
7776Evaluation for arbitrarily chosen `s` and `z`::
7778 >>> from mpmath import *
7779 >>> mp.dps = 25; mp.pretty = True
7780 >>> s, z = 3, 4
7781 >>> clsin(s, z); nsum(lambda k: sin(z*k)/k**s, [1,inf])
7782 -0.6533010136329338746275795
7783 -0.6533010136329338746275795
7785Using `z + \pi` instead of `z` gives an alternating series::
7787 >>> clsin(s, z+pi)
7788 0.8860032351260589402871624
7789 >>> nsum(lambda k: (-1)**k*sin(z*k)/k**s, [1,inf])
7790 0.8860032351260589402871624
7792With `s = 1`, the sum can be expressed in closed form
7793using elementary functions::
7795 >>> z = 1 + sqrt(3)
7796 >>> clsin(1, z)
7797 0.2047709230104579724675985
7798 >>> chop((log(1-exp(-j*z)) - log(1-exp(j*z)))/(2*j))
7799 0.2047709230104579724675985
7800 >>> nsum(lambda k: sin(k*z)/k, [1,inf])
7801 0.2047709230104579724675985
7803The classical Clausen function `\mathrm{Cl}_2(\theta)` gives the
7804value of the integral `\int_0^{\theta} -\ln(2\sin(x/2)) dx` for
7805`0 < \theta < 2 \pi`::
7807 >>> cl2 = lambda t: clsin(2, t)
7808 >>> cl2(3.5)
7809 -0.2465045302347694216534255
7810 >>> -quad(lambda x: ln(2*sin(0.5*x)), [0, 3.5])
7811 -0.2465045302347694216534255
7813This function is symmetric about `\theta = \pi` with zeros and extreme
7814points::
7816 >>> cl2(0); cl2(pi/3); chop(cl2(pi)); cl2(5*pi/3); chop(cl2(2*pi))
7817 0.0
7818 1.014941606409653625021203
7819 0.0
7820 -1.014941606409653625021203
7821 0.0
7823Catalan's constant is a special value::
7825 >>> cl2(pi/2)
7826 0.9159655941772190150546035
7827 >>> +catalan
7828 0.9159655941772190150546035
7830The Clausen sine function can be expressed in closed form when
7831`s` is an odd integer (becoming zero when `s` < 0)::
7833 >>> z = 1 + sqrt(2)
7834 >>> clsin(1, z); (pi-z)/2
7835 0.3636895456083490948304773
7836 0.3636895456083490948304773
7837 >>> clsin(3, z); pi**2/6*z - pi*z**2/4 + z**3/12
7838 0.5661751584451144991707161
7839 0.5661751584451144991707161
7840 >>> clsin(-1, z)
7841 0.0
7842 >>> clsin(-3, z)
7843 0.0
7845It can also be expressed in closed form for even integer `s \le 0`,
7846providing a finite sum for series such as
7847`\sin(z) + \sin(2z) + \sin(3z) + \ldots`::
7849 >>> z = 1 + sqrt(2)
7850 >>> clsin(0, z)
7851 0.1903105029507513881275865
7852 >>> cot(z/2)/2
7853 0.1903105029507513881275865
7854 >>> clsin(-2, z)
7855 -0.1089406163841548817581392
7856 >>> -cot(z/2)*csc(z/2)**2/4
7857 -0.1089406163841548817581392
7859Call with ``pi=True`` to multiply `z` by `\pi` exactly::
7861 >>> clsin(3, 3*pi)
7862 -8.892316224968072424732898e-26
7863 >>> clsin(3, 3, pi=True)
7864 0.0
7866Evaluation for complex `s`, `z` in a nonconvergent case::
7868 >>> s, z = -1-j, 1+2j
7869 >>> clsin(s, z)
7870 (-0.593079480117379002516034 + 0.9038644233367868273362446j)
7871 >>> extraprec(20)(nsum)(lambda k: sin(k*z)/k**s, [1,inf])
7872 (-0.593079480117379002516034 + 0.9038644233367868273362446j)
7874"""
7876clcos = r"""
7877Computes the Clausen cosine function, defined formally by the series
7879.. math ::
7881 \mathrm{\widetilde{Cl}}_s(z) = \sum_{k=1}^{\infty} \frac{\cos(kz)}{k^s}.
7883This function is complementary to the Clausen sine function
7884:func:`~mpmath.clsin`. In terms of the polylogarithm,
7886.. math ::
7888 \mathrm{\widetilde{Cl}}_s(z) =
7889 \frac{1}{2}\left(\mathrm{Li}_s\left(e^{iz}\right) +
7890 \mathrm{Li}_s\left(e^{-iz}\right)\right)
7892 = \mathrm{Re}\left[\mathrm{Li}_s(e^{iz})\right] \quad (s, z \in \mathbb{R}).
7894**Examples**
7896Evaluation for arbitrarily chosen `s` and `z`::
7898 >>> from mpmath import *
7899 >>> mp.dps = 25; mp.pretty = True
7900 >>> s, z = 3, 4
7901 >>> clcos(s, z); nsum(lambda k: cos(z*k)/k**s, [1,inf])
7902 -0.6518926267198991308332759
7903 -0.6518926267198991308332759
7905Using `z + \pi` instead of `z` gives an alternating series::
7907 >>> s, z = 3, 0.5
7908 >>> clcos(s, z+pi)
7909 -0.8155530586502260817855618
7910 >>> nsum(lambda k: (-1)**k*cos(z*k)/k**s, [1,inf])
7911 -0.8155530586502260817855618
7913With `s = 1`, the sum can be expressed in closed form
7914using elementary functions::
7916 >>> z = 1 + sqrt(3)
7917 >>> clcos(1, z)
7918 -0.6720334373369714849797918
7919 >>> chop(-0.5*(log(1-exp(j*z))+log(1-exp(-j*z))))
7920 -0.6720334373369714849797918
7921 >>> -log(abs(2*sin(0.5*z))) # Equivalent to above when z is real
7922 -0.6720334373369714849797918
7923 >>> nsum(lambda k: cos(k*z)/k, [1,inf])
7924 -0.6720334373369714849797918
7926It can also be expressed in closed form when `s` is an even integer.
7927For example,
7929 >>> clcos(2,z)
7930 -0.7805359025135583118863007
7931 >>> pi**2/6 - pi*z/2 + z**2/4
7932 -0.7805359025135583118863007
7934The case `s = 0` gives the renormalized sum of
7935`\cos(z) + \cos(2z) + \cos(3z) + \ldots` (which happens to be the same for
7936any value of `z`)::
7938 >>> clcos(0, z)
7939 -0.5
7940 >>> nsum(lambda k: cos(k*z), [1,inf])
7941 -0.5
7943Also the sums
7945.. math ::
7947 \cos(z) + 2\cos(2z) + 3\cos(3z) + \ldots
7949and
7951.. math ::
7953 \cos(z) + 2^n \cos(2z) + 3^n \cos(3z) + \ldots
7955for higher integer powers `n = -s` can be done in closed form. They are zero
7956when `n` is positive and even (`s` negative and even)::
7958 >>> clcos(-1, z); 1/(2*cos(z)-2)
7959 -0.2607829375240542480694126
7960 -0.2607829375240542480694126
7961 >>> clcos(-3, z); (2+cos(z))*csc(z/2)**4/8
7962 0.1472635054979944390848006
7963 0.1472635054979944390848006
7964 >>> clcos(-2, z); clcos(-4, z); clcos(-6, z)
7965 0.0
7966 0.0
7967 0.0
7969With `z = \pi`, the series reduces to that of the Riemann zeta function
7970(more generally, if `z = p \pi/q`, it is a finite sum over Hurwitz zeta
7971function values)::
7973 >>> clcos(2.5, 0); zeta(2.5)
7974 1.34148725725091717975677
7975 1.34148725725091717975677
7976 >>> clcos(2.5, pi); -altzeta(2.5)
7977 -0.8671998890121841381913472
7978 -0.8671998890121841381913472
7980Call with ``pi=True`` to multiply `z` by `\pi` exactly::
7982 >>> clcos(-3, 2*pi)
7983 2.997921055881167659267063e+102
7984 >>> clcos(-3, 2, pi=True)
7985 0.008333333333333333333333333
7987Evaluation for complex `s`, `z` in a nonconvergent case::
7989 >>> s, z = -1-j, 1+2j
7990 >>> clcos(s, z)
7991 (0.9407430121562251476136807 + 0.715826296033590204557054j)
7992 >>> extraprec(20)(nsum)(lambda k: cos(k*z)/k**s, [1,inf])
7993 (0.9407430121562251476136807 + 0.715826296033590204557054j)
7995"""
7997whitm = r"""
7998Evaluates the Whittaker function `M(k,m,z)`, which gives a solution
7999to the Whittaker differential equation
8001.. math ::
8003 \frac{d^2f}{dz^2} + \left(-\frac{1}{4}+\frac{k}{z}+
8004 \frac{(\frac{1}{4}-m^2)}{z^2}\right) f = 0.
8006A second solution is given by :func:`~mpmath.whitw`.
8008The Whittaker functions are defined in Abramowitz & Stegun, section 13.1.
8009They are alternate forms of the confluent hypergeometric functions
8010`\,_1F_1` and `U`:
8012.. math ::
8014 M(k,m,z) = e^{-\frac{1}{2}z} z^{\frac{1}{2}+m}
8015 \,_1F_1(\tfrac{1}{2}+m-k, 1+2m, z)
8017 W(k,m,z) = e^{-\frac{1}{2}z} z^{\frac{1}{2}+m}
8018 U(\tfrac{1}{2}+m-k, 1+2m, z).
8020**Examples**
8022Evaluation for arbitrary real and complex arguments is supported::
8024 >>> from mpmath import *
8025 >>> mp.dps = 25; mp.pretty = True
8026 >>> whitm(1, 1, 1)
8027 0.7302596799460411820509668
8028 >>> whitm(1, 1, -1)
8029 (0.0 - 1.417977827655098025684246j)
8030 >>> whitm(j, j/2, 2+3j)
8031 (3.245477713363581112736478 - 0.822879187542699127327782j)
8032 >>> whitm(2, 3, 100000)
8033 4.303985255686378497193063e+21707
8035Evaluation at zero::
8037 >>> whitm(1,-1,0); whitm(1,-0.5,0); whitm(1,0,0)
8038 +inf
8039 nan
8040 0.0
8042We can verify that :func:`~mpmath.whitm` numerically satisfies the
8043differential equation for arbitrarily chosen values::
8045 >>> k = mpf(0.25)
8046 >>> m = mpf(1.5)
8047 >>> f = lambda z: whitm(k,m,z)
8048 >>> for z in [-1, 2.5, 3, 1+2j]:
8049 ... chop(diff(f,z,2) + (-0.25 + k/z + (0.25-m**2)/z**2)*f(z))
8050 ...
8051 0.0
8052 0.0
8053 0.0
8054 0.0
8056An integral involving both :func:`~mpmath.whitm` and :func:`~mpmath.whitw`,
8057verifying evaluation along the real axis::
8059 >>> quad(lambda x: exp(-x)*whitm(3,2,x)*whitw(1,-2,x), [0,inf])
8060 3.438869842576800225207341
8061 >>> 128/(21*sqrt(pi))
8062 3.438869842576800225207341
8064"""
8066whitw = r"""
8067Evaluates the Whittaker function `W(k,m,z)`, which gives a second
8068solution to the Whittaker differential equation. (See :func:`~mpmath.whitm`.)
8070**Examples**
8072Evaluation for arbitrary real and complex arguments is supported::
8074 >>> from mpmath import *
8075 >>> mp.dps = 25; mp.pretty = True
8076 >>> whitw(1, 1, 1)
8077 1.19532063107581155661012
8078 >>> whitw(1, 1, -1)
8079 (-0.9424875979222187313924639 - 0.2607738054097702293308689j)
8080 >>> whitw(j, j/2, 2+3j)
8081 (0.1782899315111033879430369 - 0.01609578360403649340169406j)
8082 >>> whitw(2, 3, 100000)
8083 1.887705114889527446891274e-21705
8084 >>> whitw(-1, -1, 100)
8085 1.905250692824046162462058e-24
8087Evaluation at zero::
8089 >>> for m in [-1, -0.5, 0, 0.5, 1]:
8090 ... whitw(1, m, 0)
8091 ...
8092 +inf
8093 nan
8094 0.0
8095 nan
8096 +inf
8098We can verify that :func:`~mpmath.whitw` numerically satisfies the
8099differential equation for arbitrarily chosen values::
8101 >>> k = mpf(0.25)
8102 >>> m = mpf(1.5)
8103 >>> f = lambda z: whitw(k,m,z)
8104 >>> for z in [-1, 2.5, 3, 1+2j]:
8105 ... chop(diff(f,z,2) + (-0.25 + k/z + (0.25-m**2)/z**2)*f(z))
8106 ...
8107 0.0
8108 0.0
8109 0.0
8110 0.0
8112"""
8114ber = r"""
8115Computes the Kelvin function ber, which for real arguments gives the real part
8116of the Bessel J function of a rotated argument
8118.. math ::
8120 J_n\left(x e^{3\pi i/4}\right) = \mathrm{ber}_n(x) + i \mathrm{bei}_n(x).
8122The imaginary part is given by :func:`~mpmath.bei`.
8124**Plots**
8126.. literalinclude :: /plots/ber.py
8127.. image :: /plots/ber.png
8129**Examples**
8131Verifying the defining relation::
8133 >>> from mpmath import *
8134 >>> mp.dps = 25; mp.pretty = True
8135 >>> n, x = 2, 3.5
8136 >>> ber(n,x)
8137 1.442338852571888752631129
8138 >>> bei(n,x)
8139 -0.948359035324558320217678
8140 >>> besselj(n, x*root(1,8,3))
8141 (1.442338852571888752631129 - 0.948359035324558320217678j)
8143The ber and bei functions are also defined by analytic continuation
8144for complex arguments::
8146 >>> ber(1+j, 2+3j)
8147 (4.675445984756614424069563 - 15.84901771719130765656316j)
8148 >>> bei(1+j, 2+3j)
8149 (15.83886679193707699364398 + 4.684053288183046528703611j)
8151"""
8153bei = r"""
8154Computes the Kelvin function bei, which for real arguments gives the
8155imaginary part of the Bessel J function of a rotated argument.
8156See :func:`~mpmath.ber`.
8157"""
8159ker = r"""
8160Computes the Kelvin function ker, which for real arguments gives the real part
8161of the (rescaled) Bessel K function of a rotated argument
8163.. math ::
8165 e^{-\pi i/2} K_n\left(x e^{3\pi i/4}\right) = \mathrm{ker}_n(x) + i \mathrm{kei}_n(x).
8167The imaginary part is given by :func:`~mpmath.kei`.
8169**Plots**
8171.. literalinclude :: /plots/ker.py
8172.. image :: /plots/ker.png
8174**Examples**
8176Verifying the defining relation::
8178 >>> from mpmath import *
8179 >>> mp.dps = 25; mp.pretty = True
8180 >>> n, x = 2, 4.5
8181 >>> ker(n,x)
8182 0.02542895201906369640249801
8183 >>> kei(n,x)
8184 -0.02074960467222823237055351
8185 >>> exp(-n*pi*j/2) * besselk(n, x*root(1,8,1))
8186 (0.02542895201906369640249801 - 0.02074960467222823237055351j)
8188The ker and kei functions are also defined by analytic continuation
8189for complex arguments::
8191 >>> ker(1+j, 3+4j)
8192 (1.586084268115490421090533 - 2.939717517906339193598719j)
8193 >>> kei(1+j, 3+4j)
8194 (-2.940403256319453402690132 - 1.585621643835618941044855j)
8196"""
8198kei = r"""
8199Computes the Kelvin function kei, which for real arguments gives the
8200imaginary part of the (rescaled) Bessel K function of a rotated argument.
8201See :func:`~mpmath.ker`.
8202"""
8204struveh = r"""
8205Gives the Struve function
8207.. math ::
8209 \,\mathbf{H}_n(z) =
8210 \sum_{k=0}^\infty \frac{(-1)^k}{\Gamma(k+\frac{3}{2})
8211 \Gamma(k+n+\frac{3}{2})} {\left({\frac{z}{2}}\right)}^{2k+n+1}
8213which is a solution to the Struve differential equation
8215.. math ::
8217 z^2 f''(z) + z f'(z) + (z^2-n^2) f(z) = \frac{2 z^{n+1}}{\pi (2n-1)!!}.
8219**Examples**
8221Evaluation for arbitrary real and complex arguments::
8223 >>> from mpmath import *
8224 >>> mp.dps = 25; mp.pretty = True
8225 >>> struveh(0, 3.5)
8226 0.3608207733778295024977797
8227 >>> struveh(-1, 10)
8228 -0.255212719726956768034732
8229 >>> struveh(1, -100.5)
8230 0.5819566816797362287502246
8231 >>> struveh(2.5, 10000000000000)
8232 3153915652525200060.308937
8233 >>> struveh(2.5, -10000000000000)
8234 (0.0 - 3153915652525200060.308937j)
8235 >>> struveh(1+j, 1000000+4000000j)
8236 (-3.066421087689197632388731e+1737173 - 1.596619701076529803290973e+1737173j)
8238A Struve function of half-integer order is elementary; for example:
8240 >>> z = 3
8241 >>> struveh(0.5, 3)
8242 0.9167076867564138178671595
8243 >>> sqrt(2/(pi*z))*(1-cos(z))
8244 0.9167076867564138178671595
8246Numerically verifying the differential equation::
8248 >>> z = mpf(4.5)
8249 >>> n = 3
8250 >>> f = lambda z: struveh(n,z)
8251 >>> lhs = z**2*diff(f,z,2) + z*diff(f,z) + (z**2-n**2)*f(z)
8252 >>> rhs = 2*z**(n+1)/fac2(2*n-1)/pi
8253 >>> lhs
8254 17.40359302709875496632744
8255 >>> rhs
8256 17.40359302709875496632744
8258"""
8260struvel = r"""
8261Gives the modified Struve function
8263.. math ::
8265 \,\mathbf{L}_n(z) = -i e^{-n\pi i/2} \mathbf{H}_n(i z)
8267which solves to the modified Struve differential equation
8269.. math ::
8271 z^2 f''(z) + z f'(z) - (z^2+n^2) f(z) = \frac{2 z^{n+1}}{\pi (2n-1)!!}.
8273**Examples**
8275Evaluation for arbitrary real and complex arguments::
8277 >>> from mpmath import *
8278 >>> mp.dps = 25; mp.pretty = True
8279 >>> struvel(0, 3.5)
8280 7.180846515103737996249972
8281 >>> struvel(-1, 10)
8282 2670.994904980850550721511
8283 >>> struvel(1, -100.5)
8284 1.757089288053346261497686e+42
8285 >>> struvel(2.5, 10000000000000)
8286 4.160893281017115450519948e+4342944819025
8287 >>> struvel(2.5, -10000000000000)
8288 (0.0 - 4.160893281017115450519948e+4342944819025j)
8289 >>> struvel(1+j, 700j)
8290 (-0.1721150049480079451246076 + 0.1240770953126831093464055j)
8291 >>> struvel(1+j, 1000000+4000000j)
8292 (-2.973341637511505389128708e+434290 - 5.164633059729968297147448e+434290j)
8294Numerically verifying the differential equation::
8296 >>> z = mpf(3.5)
8297 >>> n = 3
8298 >>> f = lambda z: struvel(n,z)
8299 >>> lhs = z**2*diff(f,z,2) + z*diff(f,z) - (z**2+n**2)*f(z)
8300 >>> rhs = 2*z**(n+1)/fac2(2*n-1)/pi
8301 >>> lhs
8302 6.368850306060678353018165
8303 >>> rhs
8304 6.368850306060678353018165
8305"""
8307appellf1 = r"""
8308Gives the Appell F1 hypergeometric function of two variables,
8310.. math ::
8312 F_1(a,b_1,b_2,c,x,y) = \sum_{m=0}^{\infty} \sum_{n=0}^{\infty}
8313 \frac{(a)_{m+n} (b_1)_m (b_2)_n}{(c)_{m+n}}
8314 \frac{x^m y^n}{m! n!}.
8316This series is only generally convergent when `|x| < 1` and `|y| < 1`,
8317although :func:`~mpmath.appellf1` can evaluate an analytic continuation
8318with respecto to either variable, and sometimes both.
8320**Examples**
8322Evaluation is supported for real and complex parameters::
8324 >>> from mpmath import *
8325 >>> mp.dps = 25; mp.pretty = True
8326 >>> appellf1(1,0,0.5,1,0.5,0.25)
8327 1.154700538379251529018298
8328 >>> appellf1(1,1+j,0.5,1,0.5,0.5j)
8329 (1.138403860350148085179415 + 1.510544741058517621110615j)
8331For some integer parameters, the F1 series reduces to a polynomial::
8333 >>> appellf1(2,-4,-3,1,2,5)
8334 -816.0
8335 >>> appellf1(-5,1,2,1,4,5)
8336 -20528.0
8338The analytic continuation with respect to either `x` or `y`,
8339and sometimes with respect to both, can be evaluated::
8341 >>> appellf1(2,3,4,5,100,0.5)
8342 (0.0006231042714165329279738662 + 0.0000005769149277148425774499857j)
8343 >>> appellf1('1.1', '0.3', '0.2+2j', '0.4', '0.2', 1.5+3j)
8344 (-0.1782604566893954897128702 + 0.002472407104546216117161499j)
8345 >>> appellf1(1,2,3,4,10,12)
8346 -0.07122993830066776374929313
8348For certain arguments, F1 reduces to an ordinary hypergeometric function::
8350 >>> appellf1(1,2,3,5,0.5,0.25)
8351 1.547902270302684019335555
8352 >>> 4*hyp2f1(1,2,5,'1/3')/3
8353 1.547902270302684019335555
8354 >>> appellf1(1,2,3,4,0,1.5)
8355 (-1.717202506168937502740238 - 2.792526803190927323077905j)
8356 >>> hyp2f1(1,3,4,1.5)
8357 (-1.717202506168937502740238 - 2.792526803190927323077905j)
8359The F1 function satisfies a system of partial differential equations::
8361 >>> a,b1,b2,c,x,y = map(mpf, [1,0.5,0.25,1.125,0.25,-0.25])
8362 >>> F = lambda x,y: appellf1(a,b1,b2,c,x,y)
8363 >>> chop(x*(1-x)*diff(F,(x,y),(2,0)) +
8364 ... y*(1-x)*diff(F,(x,y),(1,1)) +
8365 ... (c-(a+b1+1)*x)*diff(F,(x,y),(1,0)) -
8366 ... b1*y*diff(F,(x,y),(0,1)) -
8367 ... a*b1*F(x,y))
8368 0.0
8369 >>>
8370 >>> chop(y*(1-y)*diff(F,(x,y),(0,2)) +
8371 ... x*(1-y)*diff(F,(x,y),(1,1)) +
8372 ... (c-(a+b2+1)*y)*diff(F,(x,y),(0,1)) -
8373 ... b2*x*diff(F,(x,y),(1,0)) -
8374 ... a*b2*F(x,y))
8375 0.0
8377The Appell F1 function allows for closed-form evaluation of various
8378integrals, such as any integral of the form
8379`\int x^r (x+a)^p (x+b)^q dx`::
8381 >>> def integral(a,b,p,q,r,x1,x2):
8382 ... a,b,p,q,r,x1,x2 = map(mpmathify, [a,b,p,q,r,x1,x2])
8383 ... f = lambda x: x**r * (x+a)**p * (x+b)**q
8384 ... def F(x):
8385 ... v = x**(r+1)/(r+1) * (a+x)**p * (b+x)**q
8386 ... v *= (1+x/a)**(-p)
8387 ... v *= (1+x/b)**(-q)
8388 ... v *= appellf1(r+1,-p,-q,2+r,-x/a,-x/b)
8389 ... return v
8390 ... print("Num. quad: %s" % quad(f, [x1,x2]))
8391 ... print("Appell F1: %s" % (F(x2)-F(x1)))
8392 ...
8393 >>> integral('1/5','4/3','-2','3','1/2',0,1)
8394 Num. quad: 9.073335358785776206576981
8395 Appell F1: 9.073335358785776206576981
8396 >>> integral('3/2','4/3','-2','3','1/2',0,1)
8397 Num. quad: 1.092829171999626454344678
8398 Appell F1: 1.092829171999626454344678
8399 >>> integral('3/2','4/3','-2','3','1/2',12,25)
8400 Num. quad: 1106.323225040235116498927
8401 Appell F1: 1106.323225040235116498927
8403Also incomplete elliptic integrals fall into this category [1]::
8405 >>> def E(z, m):
8406 ... if (pi/2).ae(z):
8407 ... return ellipe(m)
8408 ... return 2*round(re(z)/pi)*ellipe(m) + mpf(-1)**round(re(z)/pi)*\
8409 ... sin(z)*appellf1(0.5,0.5,-0.5,1.5,sin(z)**2,m*sin(z)**2)
8410 ...
8411 >>> z, m = 1, 0.5
8412 >>> E(z,m); quad(lambda t: sqrt(1-m*sin(t)**2), [0,pi/4,3*pi/4,z])
8413 0.9273298836244400669659042
8414 0.9273298836244400669659042
8415 >>> z, m = 3, 2
8416 >>> E(z,m); quad(lambda t: sqrt(1-m*sin(t)**2), [0,pi/4,3*pi/4,z])
8417 (1.057495752337234229715836 + 1.198140234735592207439922j)
8418 (1.057495752337234229715836 + 1.198140234735592207439922j)
8420**References**
84221. [WolframFunctions]_ http://functions.wolfram.com/EllipticIntegrals/EllipticE2/26/01/
84232. [SrivastavaKarlsson]_
84243. [CabralRosetti]_
84254. [Vidunas]_
84265. [Slater]_
8428"""
8430angerj = r"""
8431Gives the Anger function
8433.. math ::
8435 \mathbf{J}_{\nu}(z) = \frac{1}{\pi}
8436 \int_0^{\pi} \cos(\nu t - z \sin t) dt
8438which is an entire function of both the parameter `\nu` and
8439the argument `z`. It solves the inhomogeneous Bessel differential
8440equation
8442.. math ::
8444 f''(z) + \frac{1}{z}f'(z) + \left(1-\frac{\nu^2}{z^2}\right) f(z)
8445 = \frac{(z-\nu)}{\pi z^2} \sin(\pi \nu).
8447**Examples**
8449Evaluation for real and complex parameter and argument::
8451 >>> from mpmath import *
8452 >>> mp.dps = 25; mp.pretty = True
8453 >>> angerj(2,3)
8454 0.4860912605858910769078311
8455 >>> angerj(-3+4j, 2+5j)
8456 (-5033.358320403384472395612 + 585.8011892476145118551756j)
8457 >>> angerj(3.25, 1e6j)
8458 (4.630743639715893346570743e+434290 - 1.117960409887505906848456e+434291j)
8459 >>> angerj(-1.5, 1e6)
8460 0.0002795719747073879393087011
8462The Anger function coincides with the Bessel J-function when `\nu`
8463is an integer::
8465 >>> angerj(1,3); besselj(1,3)
8466 0.3390589585259364589255146
8467 0.3390589585259364589255146
8468 >>> angerj(1.5,3); besselj(1.5,3)
8469 0.4088969848691080859328847
8470 0.4777182150870917715515015
8472Verifying the differential equation::
8474 >>> v,z = mpf(2.25), 0.75
8475 >>> f = lambda z: angerj(v,z)
8476 >>> diff(f,z,2) + diff(f,z)/z + (1-(v/z)**2)*f(z)
8477 -0.6002108774380707130367995
8478 >>> (z-v)/(pi*z**2) * sinpi(v)
8479 -0.6002108774380707130367995
8481Verifying the integral representation::
8483 >>> angerj(v,z)
8484 0.1145380759919333180900501
8485 >>> quad(lambda t: cos(v*t-z*sin(t))/pi, [0,pi])
8486 0.1145380759919333180900501
8488**References**
84901. [DLMF]_ section 11.10: Anger-Weber Functions
8491"""
8493webere = r"""
8494Gives the Weber function
8496.. math ::
8498 \mathbf{E}_{\nu}(z) = \frac{1}{\pi}
8499 \int_0^{\pi} \sin(\nu t - z \sin t) dt
8501which is an entire function of both the parameter `\nu` and
8502the argument `z`. It solves the inhomogeneous Bessel differential
8503equation
8505.. math ::
8507 f''(z) + \frac{1}{z}f'(z) + \left(1-\frac{\nu^2}{z^2}\right) f(z)
8508 = -\frac{1}{\pi z^2} (z+\nu+(z-\nu)\cos(\pi \nu)).
8510**Examples**
8512Evaluation for real and complex parameter and argument::
8514 >>> from mpmath import *
8515 >>> mp.dps = 25; mp.pretty = True
8516 >>> webere(2,3)
8517 -0.1057668973099018425662646
8518 >>> webere(-3+4j, 2+5j)
8519 (-585.8081418209852019290498 - 5033.314488899926921597203j)
8520 >>> webere(3.25, 1e6j)
8521 (-1.117960409887505906848456e+434291 - 4.630743639715893346570743e+434290j)
8522 >>> webere(3.25, 1e6)
8523 -0.00002812518265894315604914453
8525Up to addition of a rational function of `z`, the Weber function coincides
8526with the Struve H-function when `\nu` is an integer::
8528 >>> webere(1,3); 2/pi-struveh(1,3)
8529 -0.3834897968188690177372881
8530 -0.3834897968188690177372881
8531 >>> webere(5,3); 26/(35*pi)-struveh(5,3)
8532 0.2009680659308154011878075
8533 0.2009680659308154011878075
8535Verifying the differential equation::
8537 >>> v,z = mpf(2.25), 0.75
8538 >>> f = lambda z: webere(v,z)
8539 >>> diff(f,z,2) + diff(f,z)/z + (1-(v/z)**2)*f(z)
8540 -1.097441848875479535164627
8541 >>> -(z+v+(z-v)*cospi(v))/(pi*z**2)
8542 -1.097441848875479535164627
8544Verifying the integral representation::
8546 >>> webere(v,z)
8547 0.1486507351534283744485421
8548 >>> quad(lambda t: sin(v*t-z*sin(t))/pi, [0,pi])
8549 0.1486507351534283744485421
8551**References**
85531. [DLMF]_ section 11.10: Anger-Weber Functions
8554"""
8556lommels1 = r"""
8557Gives the Lommel function `s_{\mu,\nu}` or `s^{(1)}_{\mu,\nu}`
8559.. math ::
8561 s_{\mu,\nu}(z) = \frac{z^{\mu+1}}{(\mu-\nu+1)(\mu+\nu+1)}
8562 \,_1F_2\left(1; \frac{\mu-\nu+3}{2}, \frac{\mu+\nu+3}{2};
8563 -\frac{z^2}{4} \right)
8565which solves the inhomogeneous Bessel equation
8567.. math ::
8569 z^2 f''(z) + z f'(z) + (z^2-\nu^2) f(z) = z^{\mu+1}.
8571A second solution is given by :func:`~mpmath.lommels2`.
8573**Plots**
8575.. literalinclude :: /plots/lommels1.py
8576.. image :: /plots/lommels1.png
8578**Examples**
8580An integral representation::
8582 >>> from mpmath import *
8583 >>> mp.dps = 25; mp.pretty = True
8584 >>> u,v,z = 0.25, 0.125, mpf(0.75)
8585 >>> lommels1(u,v,z)
8586 0.4276243877565150372999126
8587 >>> (bessely(v,z)*quad(lambda t: t**u*besselj(v,t), [0,z]) - \
8588 ... besselj(v,z)*quad(lambda t: t**u*bessely(v,t), [0,z]))*(pi/2)
8589 0.4276243877565150372999126
8591A special value::
8593 >>> lommels1(v,v,z)
8594 0.5461221367746048054932553
8595 >>> gamma(v+0.5)*sqrt(pi)*power(2,v-1)*struveh(v,z)
8596 0.5461221367746048054932553
8598Verifying the differential equation::
8600 >>> f = lambda z: lommels1(u,v,z)
8601 >>> z**2*diff(f,z,2) + z*diff(f,z) + (z**2-v**2)*f(z)
8602 0.6979536443265746992059141
8603 >>> z**(u+1)
8604 0.6979536443265746992059141
8606**References**
86081. [GradshteynRyzhik]_
86092. [Weisstein]_ http://mathworld.wolfram.com/LommelFunction.html
8610"""
8612lommels2 = r"""
8613Gives the second Lommel function `S_{\mu,\nu}` or `s^{(2)}_{\mu,\nu}`
8615.. math ::
8617 S_{\mu,\nu}(z) = s_{\mu,\nu}(z) + 2^{\mu-1}
8618 \Gamma\left(\tfrac{1}{2}(\mu-\nu+1)\right)
8619 \Gamma\left(\tfrac{1}{2}(\mu+\nu+1)\right) \times
8621 \left[\sin(\tfrac{1}{2}(\mu-\nu)\pi) J_{\nu}(z) -
8622 \cos(\tfrac{1}{2}(\mu-\nu)\pi) Y_{\nu}(z)
8623 \right]
8625which solves the same differential equation as
8626:func:`~mpmath.lommels1`.
8628**Plots**
8630.. literalinclude :: /plots/lommels2.py
8631.. image :: /plots/lommels2.png
8633**Examples**
8635For large `|z|`, `S_{\mu,\nu} \sim z^{\mu-1}`::
8637 >>> from mpmath import *
8638 >>> mp.dps = 25; mp.pretty = True
8639 >>> lommels2(10,2,30000)
8640 1.968299831601008419949804e+40
8641 >>> power(30000,9)
8642 1.9683e+40
8644A special value::
8646 >>> u,v,z = 0.5, 0.125, mpf(0.75)
8647 >>> lommels2(v,v,z)
8648 0.9589683199624672099969765
8649 >>> (struveh(v,z)-bessely(v,z))*power(2,v-1)*sqrt(pi)*gamma(v+0.5)
8650 0.9589683199624672099969765
8652Verifying the differential equation::
8654 >>> f = lambda z: lommels2(u,v,z)
8655 >>> z**2*diff(f,z,2) + z*diff(f,z) + (z**2-v**2)*f(z)
8656 0.6495190528383289850727924
8657 >>> z**(u+1)
8658 0.6495190528383289850727924
8660**References**
86621. [GradshteynRyzhik]_
86632. [Weisstein]_ http://mathworld.wolfram.com/LommelFunction.html
8664"""
8666appellf2 = r"""
8667Gives the Appell F2 hypergeometric function of two variables
8669.. math ::
8671 F_2(a,b_1,b_2,c_1,c_2,x,y) = \sum_{m=0}^{\infty} \sum_{n=0}^{\infty}
8672 \frac{(a)_{m+n} (b_1)_m (b_2)_n}{(c_1)_m (c_2)_n}
8673 \frac{x^m y^n}{m! n!}.
8675The series is generally absolutely convergent for `|x| + |y| < 1`.
8677**Examples**
8679Evaluation for real and complex arguments::
8681 >>> from mpmath import *
8682 >>> mp.dps = 25; mp.pretty = True
8683 >>> appellf2(1,2,3,4,5,0.25,0.125)
8684 1.257417193533135344785602
8685 >>> appellf2(1,-3,-4,2,3,2,3)
8686 -42.8
8687 >>> appellf2(0.5,0.25,-0.25,2,3,0.25j,0.25)
8688 (0.9880539519421899867041719 + 0.01497616165031102661476978j)
8689 >>> chop(appellf2(1,1+j,1-j,3j,-3j,0.25,0.25))
8690 1.201311219287411337955192
8691 >>> appellf2(1,1,1,4,6,0.125,16)
8692 (-0.09455532250274744282125152 - 0.7647282253046207836769297j)
8694A transformation formula::
8696 >>> a,b1,b2,c1,c2,x,y = map(mpf, [1,2,0.5,0.25,1.625,-0.125,0.125])
8697 >>> appellf2(a,b1,b2,c1,c2,x,y)
8698 0.2299211717841180783309688
8699 >>> (1-x)**(-a)*appellf2(a,c1-b1,b2,c1,c2,x/(x-1),y/(1-x))
8700 0.2299211717841180783309688
8702A system of partial differential equations satisfied by F2::
8704 >>> a,b1,b2,c1,c2,x,y = map(mpf, [1,0.5,0.25,1.125,1.5,0.0625,-0.0625])
8705 >>> F = lambda x,y: appellf2(a,b1,b2,c1,c2,x,y)
8706 >>> chop(x*(1-x)*diff(F,(x,y),(2,0)) -
8707 ... x*y*diff(F,(x,y),(1,1)) +
8708 ... (c1-(a+b1+1)*x)*diff(F,(x,y),(1,0)) -
8709 ... b1*y*diff(F,(x,y),(0,1)) -
8710 ... a*b1*F(x,y))
8711 0.0
8712 >>> chop(y*(1-y)*diff(F,(x,y),(0,2)) -
8713 ... x*y*diff(F,(x,y),(1,1)) +
8714 ... (c2-(a+b2+1)*y)*diff(F,(x,y),(0,1)) -
8715 ... b2*x*diff(F,(x,y),(1,0)) -
8716 ... a*b2*F(x,y))
8717 0.0
8719**References**
8721See references for :func:`~mpmath.appellf1`.
8722"""
8724appellf3 = r"""
8725Gives the Appell F3 hypergeometric function of two variables
8727.. math ::
8729 F_3(a_1,a_2,b_1,b_2,c,x,y) = \sum_{m=0}^{\infty} \sum_{n=0}^{\infty}
8730 \frac{(a_1)_m (a_2)_n (b_1)_m (b_2)_n}{(c)_{m+n}}
8731 \frac{x^m y^n}{m! n!}.
8733The series is generally absolutely convergent for `|x| < 1, |y| < 1`.
8735**Examples**
8737Evaluation for various parameters and variables::
8739 >>> from mpmath import *
8740 >>> mp.dps = 25; mp.pretty = True
8741 >>> appellf3(1,2,3,4,5,0.5,0.25)
8742 2.221557778107438938158705
8743 >>> appellf3(1,2,3,4,5,6,0); hyp2f1(1,3,5,6)
8744 (-0.5189554589089861284537389 - 0.1454441043328607980769742j)
8745 (-0.5189554589089861284537389 - 0.1454441043328607980769742j)
8746 >>> appellf3(1,-2,-3,1,1,4,6)
8747 -17.4
8748 >>> appellf3(1,2,-3,1,1,4,6)
8749 (17.7876136773677356641825 + 19.54768762233649126154534j)
8750 >>> appellf3(1,2,-3,1,1,6,4)
8751 (85.02054175067929402953645 + 148.4402528821177305173599j)
8752 >>> chop(appellf3(1+j,2,1-j,2,3,0.25,0.25))
8753 1.719992169545200286696007
8755Many transformations and evaluations for special combinations
8756of the parameters are possible, e.g.:
8758 >>> a,b,c,x,y = map(mpf, [0.5,0.25,0.125,0.125,-0.125])
8759 >>> appellf3(a,c-a,b,c-b,c,x,y)
8760 1.093432340896087107444363
8761 >>> (1-y)**(a+b-c)*hyp2f1(a,b,c,x+y-x*y)
8762 1.093432340896087107444363
8763 >>> x**2*appellf3(1,1,1,1,3,x,-x)
8764 0.01568646277445385390945083
8765 >>> polylog(2,x**2)
8766 0.01568646277445385390945083
8767 >>> a1,a2,b1,b2,c,x = map(mpf, [0.5,0.25,0.125,0.5,4.25,0.125])
8768 >>> appellf3(a1,a2,b1,b2,c,x,1)
8769 1.03947361709111140096947
8770 >>> gammaprod([c,c-a2-b2],[c-a2,c-b2])*hyp3f2(a1,b1,c-a2-b2,c-a2,c-b2,x)
8771 1.03947361709111140096947
8773The Appell F3 function satisfies a pair of partial
8774differential equations::
8776 >>> a1,a2,b1,b2,c,x,y = map(mpf, [0.5,0.25,0.125,0.5,0.625,0.0625,-0.0625])
8777 >>> F = lambda x,y: appellf3(a1,a2,b1,b2,c,x,y)
8778 >>> chop(x*(1-x)*diff(F,(x,y),(2,0)) +
8779 ... y*diff(F,(x,y),(1,1)) +
8780 ... (c-(a1+b1+1)*x)*diff(F,(x,y),(1,0)) -
8781 ... a1*b1*F(x,y))
8782 0.0
8783 >>> chop(y*(1-y)*diff(F,(x,y),(0,2)) +
8784 ... x*diff(F,(x,y),(1,1)) +
8785 ... (c-(a2+b2+1)*y)*diff(F,(x,y),(0,1)) -
8786 ... a2*b2*F(x,y))
8787 0.0
8789**References**
8791See references for :func:`~mpmath.appellf1`.
8792"""
8794appellf4 = r"""
8795Gives the Appell F4 hypergeometric function of two variables
8797.. math ::
8799 F_4(a,b,c_1,c_2,x,y) = \sum_{m=0}^{\infty} \sum_{n=0}^{\infty}
8800 \frac{(a)_{m+n} (b)_{m+n}}{(c_1)_m (c_2)_n}
8801 \frac{x^m y^n}{m! n!}.
8803The series is generally absolutely convergent for
8804`\sqrt{|x|} + \sqrt{|y|} < 1`.
8806**Examples**
8808Evaluation for various parameters and arguments::
8810 >>> from mpmath import *
8811 >>> mp.dps = 25; mp.pretty = True
8812 >>> appellf4(1,1,2,2,0.25,0.125)
8813 1.286182069079718313546608
8814 >>> appellf4(-2,-3,4,5,4,5)
8815 34.8
8816 >>> appellf4(5,4,2,3,0.25j,-0.125j)
8817 (-0.2585967215437846642163352 + 2.436102233553582711818743j)
8819Reduction to `\,_2F_1` in a special case::
8821 >>> a,b,c,x,y = map(mpf, [0.5,0.25,0.125,0.125,-0.125])
8822 >>> appellf4(a,b,c,a+b-c+1,x*(1-y),y*(1-x))
8823 1.129143488466850868248364
8824 >>> hyp2f1(a,b,c,x)*hyp2f1(a,b,a+b-c+1,y)
8825 1.129143488466850868248364
8827A system of partial differential equations satisfied by F4::
8829 >>> a,b,c1,c2,x,y = map(mpf, [1,0.5,0.25,1.125,0.0625,-0.0625])
8830 >>> F = lambda x,y: appellf4(a,b,c1,c2,x,y)
8831 >>> chop(x*(1-x)*diff(F,(x,y),(2,0)) -
8832 ... y**2*diff(F,(x,y),(0,2)) -
8833 ... 2*x*y*diff(F,(x,y),(1,1)) +
8834 ... (c1-(a+b+1)*x)*diff(F,(x,y),(1,0)) -
8835 ... ((a+b+1)*y)*diff(F,(x,y),(0,1)) -
8836 ... a*b*F(x,y))
8837 0.0
8838 >>> chop(y*(1-y)*diff(F,(x,y),(0,2)) -
8839 ... x**2*diff(F,(x,y),(2,0)) -
8840 ... 2*x*y*diff(F,(x,y),(1,1)) +
8841 ... (c2-(a+b+1)*y)*diff(F,(x,y),(0,1)) -
8842 ... ((a+b+1)*x)*diff(F,(x,y),(1,0)) -
8843 ... a*b*F(x,y))
8844 0.0
8846**References**
8848See references for :func:`~mpmath.appellf1`.
8849"""
8851zeta = r"""
8852Computes the Riemann zeta function
8854.. math ::
8856 \zeta(s) = 1+\frac{1}{2^s}+\frac{1}{3^s}+\frac{1}{4^s}+\ldots
8858or, with `a \ne 1`, the more general Hurwitz zeta function
8860.. math ::
8862 \zeta(s,a) = \sum_{k=0}^\infty \frac{1}{(a+k)^s}.
8864Optionally, ``zeta(s, a, n)`` computes the `n`-th derivative with
8865respect to `s`,
8867.. math ::
8869 \zeta^{(n)}(s,a) = (-1)^n \sum_{k=0}^\infty \frac{\log^n(a+k)}{(a+k)^s}.
8871Although these series only converge for `\Re(s) > 1`, the Riemann and Hurwitz
8872zeta functions are defined through analytic continuation for arbitrary
8873complex `s \ne 1` (`s = 1` is a pole).
8875The implementation uses three algorithms: the Borwein algorithm for
8876the Riemann zeta function when `s` is close to the real line;
8877the Riemann-Siegel formula for the Riemann zeta function when `s` is
8878large imaginary, and Euler-Maclaurin summation in all other cases.
8879The reflection formula for `\Re(s) < 0` is implemented in some cases.
8880The algorithm can be chosen with ``method = 'borwein'``,
8881``method='riemann-siegel'`` or ``method = 'euler-maclaurin'``.
8883The parameter `a` is usually a rational number `a = p/q`, and may be specified
8884as such by passing an integer tuple `(p, q)`. Evaluation is supported for
8885arbitrary complex `a`, but may be slow and/or inaccurate when `\Re(s) < 0` for
8886nonrational `a` or when computing derivatives.
8888**Examples**
8890Some values of the Riemann zeta function::
8892 >>> from mpmath import *
8893 >>> mp.dps = 25; mp.pretty = True
8894 >>> zeta(2); pi**2 / 6
8895 1.644934066848226436472415
8896 1.644934066848226436472415
8897 >>> zeta(0)
8898 -0.5
8899 >>> zeta(-1)
8900 -0.08333333333333333333333333
8901 >>> zeta(-2)
8902 0.0
8904For large positive `s`, `\zeta(s)` rapidly approaches 1::
8906 >>> zeta(50)
8907 1.000000000000000888178421
8908 >>> zeta(100)
8909 1.0
8910 >>> zeta(inf)
8911 1.0
8912 >>> 1-sum((zeta(k)-1)/k for k in range(2,85)); +euler
8913 0.5772156649015328606065121
8914 0.5772156649015328606065121
8915 >>> nsum(lambda k: zeta(k)-1, [2, inf])
8916 1.0
8918Evaluation is supported for complex `s` and `a`:
8920 >>> zeta(-3+4j)
8921 (-0.03373057338827757067584698 + 0.2774499251557093745297677j)
8922 >>> zeta(2+3j, -1+j)
8923 (389.6841230140842816370741 + 295.2674610150305334025962j)
8925The Riemann zeta function has so-called nontrivial zeros on
8926the critical line `s = 1/2 + it`::
8928 >>> findroot(zeta, 0.5+14j); zetazero(1)
8929 (0.5 + 14.13472514173469379045725j)
8930 (0.5 + 14.13472514173469379045725j)
8931 >>> findroot(zeta, 0.5+21j); zetazero(2)
8932 (0.5 + 21.02203963877155499262848j)
8933 (0.5 + 21.02203963877155499262848j)
8934 >>> findroot(zeta, 0.5+25j); zetazero(3)
8935 (0.5 + 25.01085758014568876321379j)
8936 (0.5 + 25.01085758014568876321379j)
8937 >>> chop(zeta(zetazero(10)))
8938 0.0
8940Evaluation on and near the critical line is supported for large
8941heights `t` by means of the Riemann-Siegel formula (currently
8942for `a = 1`, `n \le 4`)::
8944 >>> zeta(0.5+100000j)
8945 (1.073032014857753132114076 + 5.780848544363503984261041j)
8946 >>> zeta(0.75+1000000j)
8947 (0.9535316058375145020351559 + 0.9525945894834273060175651j)
8948 >>> zeta(0.5+10000000j)
8949 (11.45804061057709254500227 - 8.643437226836021723818215j)
8950 >>> zeta(0.5+100000000j, derivative=1)
8951 (51.12433106710194942681869 + 43.87221167872304520599418j)
8952 >>> zeta(0.5+100000000j, derivative=2)
8953 (-444.2760822795430400549229 - 896.3789978119185981665403j)
8954 >>> zeta(0.5+100000000j, derivative=3)
8955 (3230.72682687670422215339 + 14374.36950073615897616781j)
8956 >>> zeta(0.5+100000000j, derivative=4)
8957 (-11967.35573095046402130602 - 218945.7817789262839266148j)
8958 >>> zeta(1+10000000j) # off the line
8959 (2.859846483332530337008882 + 0.491808047480981808903986j)
8960 >>> zeta(1+10000000j, derivative=1)
8961 (-4.333835494679647915673205 - 0.08405337962602933636096103j)
8962 >>> zeta(1+10000000j, derivative=4)
8963 (453.2764822702057701894278 - 581.963625832768189140995j)
8965For investigation of the zeta function zeros, the Riemann-Siegel
8966Z-function is often more convenient than working with the Riemann
8967zeta function directly (see :func:`~mpmath.siegelz`).
8969Some values of the Hurwitz zeta function::
8971 >>> zeta(2, 3); -5./4 + pi**2/6
8972 0.3949340668482264364724152
8973 0.3949340668482264364724152
8974 >>> zeta(2, (3,4)); pi**2 - 8*catalan
8975 2.541879647671606498397663
8976 2.541879647671606498397663
8978For positive integer values of `s`, the Hurwitz zeta function is
8979equivalent to a polygamma function (except for a normalizing factor)::
8981 >>> zeta(4, (1,5)); psi(3, '1/5')/6
8982 625.5408324774542966919938
8983 625.5408324774542966919938
8985Evaluation of derivatives::
8987 >>> zeta(0, 3+4j, 1); loggamma(3+4j) - ln(2*pi)/2
8988 (-2.675565317808456852310934 + 4.742664438034657928194889j)
8989 (-2.675565317808456852310934 + 4.742664438034657928194889j)
8990 >>> zeta(2, 1, 20)
8991 2432902008176640000.000242
8992 >>> zeta(3+4j, 5.5+2j, 4)
8993 (-0.140075548947797130681075 - 0.3109263360275413251313634j)
8994 >>> zeta(0.5+100000j, 1, 4)
8995 (-10407.16081931495861539236 + 13777.78669862804508537384j)
8996 >>> zeta(-100+0.5j, (1,3), derivative=4)
8997 (4.007180821099823942702249e+79 + 4.916117957092593868321778e+78j)
8999Generating a Taylor series at `s = 2` using derivatives::
9001 >>> for k in range(11): print("%s * (s-2)^%i" % (zeta(2,1,k)/fac(k), k))
9002 ...
9003 1.644934066848226436472415 * (s-2)^0
9004 -0.9375482543158437537025741 * (s-2)^1
9005 0.9946401171494505117104293 * (s-2)^2
9006 -1.000024300473840810940657 * (s-2)^3
9007 1.000061933072352565457512 * (s-2)^4
9008 -1.000006869443931806408941 * (s-2)^5
9009 1.000000173233769531820592 * (s-2)^6
9010 -0.9999999569989868493432399 * (s-2)^7
9011 0.9999999937218844508684206 * (s-2)^8
9012 -0.9999999996355013916608284 * (s-2)^9
9013 1.000000000004610645020747 * (s-2)^10
9015Evaluation at zero and for negative integer `s`::
9017 >>> zeta(0, 10)
9018 -9.5
9019 >>> zeta(-2, (2,3)); mpf(1)/81
9020 0.01234567901234567901234568
9021 0.01234567901234567901234568
9022 >>> zeta(-3+4j, (5,4))
9023 (0.2899236037682695182085988 + 0.06561206166091757973112783j)
9024 >>> zeta(-3.25, 1/pi)
9025 -0.0005117269627574430494396877
9026 >>> zeta(-3.5, pi, 1)
9027 11.156360390440003294709
9028 >>> zeta(-100.5, (8,3))
9029 -4.68162300487989766727122e+77
9030 >>> zeta(-10.5, (-8,3))
9031 (-0.01521913704446246609237979 + 29907.72510874248161608216j)
9032 >>> zeta(-1000.5, (-8,3))
9033 (1.031911949062334538202567e+1770 + 1.519555750556794218804724e+426j)
9034 >>> zeta(-1+j, 3+4j)
9035 (-16.32988355630802510888631 - 22.17706465801374033261383j)
9036 >>> zeta(-1+j, 3+4j, 2)
9037 (32.48985276392056641594055 - 51.11604466157397267043655j)
9038 >>> diff(lambda s: zeta(s, 3+4j), -1+j, 2)
9039 (32.48985276392056641594055 - 51.11604466157397267043655j)
9041**References**
90431. http://mathworld.wolfram.com/RiemannZetaFunction.html
90452. http://mathworld.wolfram.com/HurwitzZetaFunction.html
90473. http://www.cecm.sfu.ca/personal/pborwein/PAPERS/P155.pdf
9049"""
9051dirichlet = r"""
9052Evaluates the Dirichlet L-function
9054.. math ::
9056 L(s,\chi) = \sum_{k=1}^\infty \frac{\chi(k)}{k^s}.
9058where `\chi` is a periodic sequence of length `q` which should be supplied
9059in the form of a list `[\chi(0), \chi(1), \ldots, \chi(q-1)]`.
9060Strictly, `\chi` should be a Dirichlet character, but any periodic
9061sequence will work.
9063For example, ``dirichlet(s, [1])`` gives the ordinary
9064Riemann zeta function and ``dirichlet(s, [-1,1])`` gives
9065the alternating zeta function (Dirichlet eta function).
9067Also the derivative with respect to `s` (currently only a first
9068derivative) can be evaluated.
9070**Examples**
9072The ordinary Riemann zeta function::
9074 >>> from mpmath import *
9075 >>> mp.dps = 25; mp.pretty = True
9076 >>> dirichlet(3, [1]); zeta(3)
9077 1.202056903159594285399738
9078 1.202056903159594285399738
9079 >>> dirichlet(1, [1])
9080 +inf
9082The alternating zeta function::
9084 >>> dirichlet(1, [-1,1]); ln(2)
9085 0.6931471805599453094172321
9086 0.6931471805599453094172321
9088The following defines the Dirichlet beta function
9089`\beta(s) = \sum_{k=0}^\infty \frac{(-1)^k}{(2k+1)^s}` and verifies
9090several values of this function::
9092 >>> B = lambda s, d=0: dirichlet(s, [0, 1, 0, -1], d)
9093 >>> B(0); 1./2
9094 0.5
9095 0.5
9096 >>> B(1); pi/4
9097 0.7853981633974483096156609
9098 0.7853981633974483096156609
9099 >>> B(2); +catalan
9100 0.9159655941772190150546035
9101 0.9159655941772190150546035
9102 >>> B(2,1); diff(B, 2)
9103 0.08158073611659279510291217
9104 0.08158073611659279510291217
9105 >>> B(-1,1); 2*catalan/pi
9106 0.5831218080616375602767689
9107 0.5831218080616375602767689
9108 >>> B(0,1); log(gamma(0.25)**2/(2*pi*sqrt(2)))
9109 0.3915943927068367764719453
9110 0.3915943927068367764719454
9111 >>> B(1,1); 0.25*pi*(euler+2*ln2+3*ln(pi)-4*ln(gamma(0.25)))
9112 0.1929013167969124293631898
9113 0.1929013167969124293631898
9115A custom L-series of period 3::
9117 >>> dirichlet(2, [2,0,1])
9118 0.7059715047839078092146831
9119 >>> 2*nsum(lambda k: (3*k)**-2, [1,inf]) + \
9120 ... nsum(lambda k: (3*k+2)**-2, [0,inf])
9121 0.7059715047839078092146831
9123"""
9125coulombf = r"""
9126Calculates the regular Coulomb wave function
9128.. math ::
9130 F_l(\eta,z) = C_l(\eta) z^{l+1} e^{-iz} \,_1F_1(l+1-i\eta, 2l+2, 2iz)
9132where the normalization constant `C_l(\eta)` is as calculated by
9133:func:`~mpmath.coulombc`. This function solves the differential equation
9135.. math ::
9137 f''(z) + \left(1-\frac{2\eta}{z}-\frac{l(l+1)}{z^2}\right) f(z) = 0.
9139A second linearly independent solution is given by the irregular
9140Coulomb wave function `G_l(\eta,z)` (see :func:`~mpmath.coulombg`)
9141and thus the general solution is
9142`f(z) = C_1 F_l(\eta,z) + C_2 G_l(\eta,z)` for arbitrary
9143constants `C_1`, `C_2`.
9144Physically, the Coulomb wave functions give the radial solution
9145to the Schrodinger equation for a point particle in a `1/z` potential; `z` is
9146then the radius and `l`, `\eta` are quantum numbers.
9148The Coulomb wave functions with real parameters are defined
9149in Abramowitz & Stegun, section 14. However, all parameters are permitted
9150to be complex in this implementation (see references).
9152**Plots**
9154.. literalinclude :: /plots/coulombf.py
9155.. image :: /plots/coulombf.png
9156.. literalinclude :: /plots/coulombf_c.py
9157.. image :: /plots/coulombf_c.png
9159**Examples**
9161Evaluation is supported for arbitrary magnitudes of `z`::
9163 >>> from mpmath import *
9164 >>> mp.dps = 25; mp.pretty = True
9165 >>> coulombf(2, 1.5, 3.5)
9166 0.4080998961088761187426445
9167 >>> coulombf(-2, 1.5, 3.5)
9168 0.7103040849492536747533465
9169 >>> coulombf(2, 1.5, '1e-10')
9170 4.143324917492256448770769e-33
9171 >>> coulombf(2, 1.5, 1000)
9172 0.4482623140325567050716179
9173 >>> coulombf(2, 1.5, 10**10)
9174 -0.066804196437694360046619
9176Verifying the differential equation::
9178 >>> l, eta, z = 2, 3, mpf(2.75)
9179 >>> A, B = 1, 2
9180 >>> f = lambda z: A*coulombf(l,eta,z) + B*coulombg(l,eta,z)
9181 >>> chop(diff(f,z,2) + (1-2*eta/z - l*(l+1)/z**2)*f(z))
9182 0.0
9184A Wronskian relation satisfied by the Coulomb wave functions::
9186 >>> l = 2
9187 >>> eta = 1.5
9188 >>> F = lambda z: coulombf(l,eta,z)
9189 >>> G = lambda z: coulombg(l,eta,z)
9190 >>> for z in [3.5, -1, 2+3j]:
9191 ... chop(diff(F,z)*G(z) - F(z)*diff(G,z))
9192 ...
9193 1.0
9194 1.0
9195 1.0
9197Another Wronskian relation::
9199 >>> F = coulombf
9200 >>> G = coulombg
9201 >>> for z in [3.5, -1, 2+3j]:
9202 ... chop(F(l-1,eta,z)*G(l,eta,z)-F(l,eta,z)*G(l-1,eta,z) - l/sqrt(l**2+eta**2))
9203 ...
9204 0.0
9205 0.0
9206 0.0
9208An integral identity connecting the regular and irregular wave functions::
9210 >>> l, eta, z = 4+j, 2-j, 5+2j
9211 >>> coulombf(l,eta,z) + j*coulombg(l,eta,z)
9212 (0.7997977752284033239714479 + 0.9294486669502295512503127j)
9213 >>> g = lambda t: exp(-t)*t**(l-j*eta)*(t+2*j*z)**(l+j*eta)
9214 >>> j*exp(-j*z)*z**(-l)/fac(2*l+1)/coulombc(l,eta)*quad(g, [0,inf])
9215 (0.7997977752284033239714479 + 0.9294486669502295512503127j)
9217Some test case with complex parameters, taken from Michel [2]::
9219 >>> mp.dps = 15
9220 >>> coulombf(1+0.1j, 50+50j, 100.156)
9221 (-1.02107292320897e+15 - 2.83675545731519e+15j)
9222 >>> coulombg(1+0.1j, 50+50j, 100.156)
9223 (2.83675545731519e+15 - 1.02107292320897e+15j)
9224 >>> coulombf(1e-5j, 10+1e-5j, 0.1+1e-6j)
9225 (4.30566371247811e-14 - 9.03347835361657e-19j)
9226 >>> coulombg(1e-5j, 10+1e-5j, 0.1+1e-6j)
9227 (778709182061.134 + 18418936.2660553j)
9229The following reproduces a table in Abramowitz & Stegun, at twice
9230the precision::
9232 >>> mp.dps = 10
9233 >>> eta = 2; z = 5
9234 >>> for l in [5, 4, 3, 2, 1, 0]:
9235 ... print("%s %s %s" % (l, coulombf(l,eta,z),
9236 ... diff(lambda z: coulombf(l,eta,z), z)))
9237 ...
9238 5 0.09079533488 0.1042553261
9239 4 0.2148205331 0.2029591779
9240 3 0.4313159311 0.320534053
9241 2 0.7212774133 0.3952408216
9242 1 0.9935056752 0.3708676452
9243 0 1.143337392 0.2937960375
9245**References**
92471. I.J. Thompson & A.R. Barnett, "Coulomb and Bessel Functions of Complex
9248 Arguments and Order", J. Comp. Phys., vol 64, no. 2, June 1986.
92502. N. Michel, "Precise Coulomb wave functions for a wide range of
9251 complex `l`, `\eta` and `z`", http://arxiv.org/abs/physics/0702051v1
9253"""
9255coulombg = r"""
9256Calculates the irregular Coulomb wave function
9258.. math ::
9260 G_l(\eta,z) = \frac{F_l(\eta,z) \cos(\chi) - F_{-l-1}(\eta,z)}{\sin(\chi)}
9262where `\chi = \sigma_l - \sigma_{-l-1} - (l+1/2) \pi`
9263and `\sigma_l(\eta) = (\ln \Gamma(1+l+i\eta)-\ln \Gamma(1+l-i\eta))/(2i)`.
9265See :func:`~mpmath.coulombf` for additional information.
9267**Plots**
9269.. literalinclude :: /plots/coulombg.py
9270.. image :: /plots/coulombg.png
9271.. literalinclude :: /plots/coulombg_c.py
9272.. image :: /plots/coulombg_c.png
9274**Examples**
9276Evaluation is supported for arbitrary magnitudes of `z`::
9278 >>> from mpmath import *
9279 >>> mp.dps = 25; mp.pretty = True
9280 >>> coulombg(-2, 1.5, 3.5)
9281 1.380011900612186346255524
9282 >>> coulombg(2, 1.5, 3.5)
9283 1.919153700722748795245926
9284 >>> coulombg(-2, 1.5, '1e-10')
9285 201126715824.7329115106793
9286 >>> coulombg(-2, 1.5, 1000)
9287 0.1802071520691149410425512
9288 >>> coulombg(-2, 1.5, 10**10)
9289 0.652103020061678070929794
9291The following reproduces a table in Abramowitz & Stegun,
9292at twice the precision::
9294 >>> mp.dps = 10
9295 >>> eta = 2; z = 5
9296 >>> for l in [1, 2, 3, 4, 5]:
9297 ... print("%s %s %s" % (l, coulombg(l,eta,z),
9298 ... -diff(lambda z: coulombg(l,eta,z), z)))
9299 ...
9300 1 1.08148276 0.6028279961
9301 2 1.496877075 0.5661803178
9302 3 2.048694714 0.7959909551
9303 4 3.09408669 1.731802374
9304 5 5.629840456 4.549343289
9306Evaluation close to the singularity at `z = 0`::
9308 >>> mp.dps = 15
9309 >>> coulombg(0,10,1)
9310 3088184933.67358
9311 >>> coulombg(0,10,'1e-10')
9312 5554866000719.8
9313 >>> coulombg(0,10,'1e-100')
9314 5554866221524.1
9316Evaluation with a half-integer value for `l`::
9318 >>> coulombg(1.5, 1, 10)
9319 0.852320038297334
9320"""
9322coulombc = r"""
9323Gives the normalizing Gamow constant for Coulomb wave functions,
9325.. math ::
9327 C_l(\eta) = 2^l \exp\left(-\pi \eta/2 + [\ln \Gamma(1+l+i\eta) +
9328 \ln \Gamma(1+l-i\eta)]/2 - \ln \Gamma(2l+2)\right),
9330where the log gamma function with continuous imaginary part
9331away from the negative half axis (see :func:`~mpmath.loggamma`) is implied.
9333This function is used internally for the calculation of
9334Coulomb wave functions, and automatically cached to make multiple
9335evaluations with fixed `l`, `\eta` fast.
9336"""
9338ellipfun = r"""
9339Computes any of the Jacobi elliptic functions, defined
9340in terms of Jacobi theta functions as
9342.. math ::
9344 \mathrm{sn}(u,m) = \frac{\vartheta_3(0,q)}{\vartheta_2(0,q)}
9345 \frac{\vartheta_1(t,q)}{\vartheta_4(t,q)}
9347 \mathrm{cn}(u,m) = \frac{\vartheta_4(0,q)}{\vartheta_2(0,q)}
9348 \frac{\vartheta_2(t,q)}{\vartheta_4(t,q)}
9350 \mathrm{dn}(u,m) = \frac{\vartheta_4(0,q)}{\vartheta_3(0,q)}
9351 \frac{\vartheta_3(t,q)}{\vartheta_4(t,q)},
9353or more generally computes a ratio of two such functions. Here
9354`t = u/\vartheta_3(0,q)^2`, and `q = q(m)` denotes the nome (see
9355:func:`~mpmath.nome`). Optionally, you can specify the nome directly
9356instead of `m` by passing ``q=<value>``, or you can directly
9357specify the elliptic parameter `k` with ``k=<value>``.
9359The first argument should be a two-character string specifying the
9360function using any combination of ``'s'``, ``'c'``, ``'d'``, ``'n'``. These
9361letters respectively denote the basic functions
9362`\mathrm{sn}(u,m)`, `\mathrm{cn}(u,m)`, `\mathrm{dn}(u,m)`, and `1`.
9363The identifier specifies the ratio of two such functions.
9364For example, ``'ns'`` identifies the function
9366.. math ::
9368 \mathrm{ns}(u,m) = \frac{1}{\mathrm{sn}(u,m)}
9370and ``'cd'`` identifies the function
9372.. math ::
9374 \mathrm{cd}(u,m) = \frac{\mathrm{cn}(u,m)}{\mathrm{dn}(u,m)}.
9376If called with only the first argument, a function object
9377evaluating the chosen function for given arguments is returned.
9379**Examples**
9381Basic evaluation::
9383 >>> from mpmath import *
9384 >>> mp.dps = 25; mp.pretty = True
9385 >>> ellipfun('cd', 3.5, 0.5)
9386 -0.9891101840595543931308394
9387 >>> ellipfun('cd', 3.5, q=0.25)
9388 0.07111979240214668158441418
9390The sn-function is doubly periodic in the complex plane with periods
9391`4 K(m)` and `2 i K(1-m)` (see :func:`~mpmath.ellipk`)::
9393 >>> sn = ellipfun('sn')
9394 >>> sn(2, 0.25)
9395 0.9628981775982774425751399
9396 >>> sn(2+4*ellipk(0.25), 0.25)
9397 0.9628981775982774425751399
9398 >>> chop(sn(2+2*j*ellipk(1-0.25), 0.25))
9399 0.9628981775982774425751399
9401The cn-function is doubly periodic with periods `4 K(m)` and `2 K(m) + 2 i K(1-m)`::
9403 >>> cn = ellipfun('cn')
9404 >>> cn(2, 0.25)
9405 -0.2698649654510865792581416
9406 >>> cn(2+4*ellipk(0.25), 0.25)
9407 -0.2698649654510865792581416
9408 >>> chop(cn(2+2*ellipk(0.25)+2*j*ellipk(1-0.25), 0.25))
9409 -0.2698649654510865792581416
9411The dn-function is doubly periodic with periods `2 K(m)` and `4 i K(1-m)`::
9413 >>> dn = ellipfun('dn')
9414 >>> dn(2, 0.25)
9415 0.8764740583123262286931578
9416 >>> dn(2+2*ellipk(0.25), 0.25)
9417 0.8764740583123262286931578
9418 >>> chop(dn(2+4*j*ellipk(1-0.25), 0.25))
9419 0.8764740583123262286931578
9421"""
9424jtheta = r"""
9425Computes the Jacobi theta function `\vartheta_n(z, q)`, where
9426`n = 1, 2, 3, 4`, defined by the infinite series:
9428.. math ::
9430 \vartheta_1(z,q) = 2 q^{1/4} \sum_{n=0}^{\infty}
9431 (-1)^n q^{n^2+n\,} \sin((2n+1)z)
9433 \vartheta_2(z,q) = 2 q^{1/4} \sum_{n=0}^{\infty}
9434 q^{n^{2\,} + n} \cos((2n+1)z)
9436 \vartheta_3(z,q) = 1 + 2 \sum_{n=1}^{\infty}
9437 q^{n^2\,} \cos(2 n z)
9439 \vartheta_4(z,q) = 1 + 2 \sum_{n=1}^{\infty}
9440 (-q)^{n^2\,} \cos(2 n z)
9442The theta functions are functions of two variables:
9444* `z` is the *argument*, an arbitrary real or complex number
9446* `q` is the *nome*, which must be a real or complex number
9447 in the unit disk (i.e. `|q| < 1`). For `|q| \ll 1`, the
9448 series converge very quickly, so the Jacobi theta functions
9449 can efficiently be evaluated to high precision.
9451The compact notations `\vartheta_n(q) = \vartheta_n(0,q)`
9452and `\vartheta_n = \vartheta_n(0,q)` are also frequently
9453encountered. Finally, Jacobi theta functions are frequently
9454considered as functions of the half-period ratio `\tau`
9455and then usually denoted by `\vartheta_n(z|\tau)`.
9457Optionally, ``jtheta(n, z, q, derivative=d)`` with `d > 0` computes
9458a `d`-th derivative with respect to `z`.
9460**Examples and basic properties**
9462Considered as functions of `z`, the Jacobi theta functions may be
9463viewed as generalizations of the ordinary trigonometric functions
9464cos and sin. They are periodic functions::
9466 >>> from mpmath import *
9467 >>> mp.dps = 25; mp.pretty = True
9468 >>> jtheta(1, 0.25, '0.2')
9469 0.2945120798627300045053104
9470 >>> jtheta(1, 0.25 + 2*pi, '0.2')
9471 0.2945120798627300045053104
9473Indeed, the series defining the theta functions are essentially
9474trigonometric Fourier series. The coefficients can be retrieved
9475using :func:`~mpmath.fourier`::
9477 >>> mp.dps = 10
9478 >>> nprint(fourier(lambda x: jtheta(2, x, 0.5), [-pi, pi], 4))
9479 ([0.0, 1.68179, 0.0, 0.420448, 0.0], [0.0, 0.0, 0.0, 0.0, 0.0])
9481The Jacobi theta functions are also so-called quasiperiodic
9482functions of `z` and `\tau`, meaning that for fixed `\tau`,
9483`\vartheta_n(z, q)` and `\vartheta_n(z+\pi \tau, q)` are the same
9484except for an exponential factor::
9486 >>> mp.dps = 25
9487 >>> tau = 3*j/10
9488 >>> q = exp(pi*j*tau)
9489 >>> z = 10
9490 >>> jtheta(4, z+tau*pi, q)
9491 (-0.682420280786034687520568 + 1.526683999721399103332021j)
9492 >>> -exp(-2*j*z)/q * jtheta(4, z, q)
9493 (-0.682420280786034687520568 + 1.526683999721399103332021j)
9495The Jacobi theta functions satisfy a huge number of other
9496functional equations, such as the following identity (valid for
9497any `q`)::
9499 >>> q = mpf(3)/10
9500 >>> jtheta(3,0,q)**4
9501 6.823744089352763305137427
9502 >>> jtheta(2,0,q)**4 + jtheta(4,0,q)**4
9503 6.823744089352763305137427
9505Extensive listings of identities satisfied by the Jacobi theta
9506functions can be found in standard reference works.
9508The Jacobi theta functions are related to the gamma function
9509for special arguments::
9511 >>> jtheta(3, 0, exp(-pi))
9512 1.086434811213308014575316
9513 >>> pi**(1/4.) / gamma(3/4.)
9514 1.086434811213308014575316
9516:func:`~mpmath.jtheta` supports arbitrary precision evaluation and complex
9517arguments::
9519 >>> mp.dps = 50
9520 >>> jtheta(4, sqrt(2), 0.5)
9521 2.0549510717571539127004115835148878097035750653737
9522 >>> mp.dps = 25
9523 >>> jtheta(4, 1+2j, (1+j)/5)
9524 (7.180331760146805926356634 - 1.634292858119162417301683j)
9526Evaluation of derivatives::
9528 >>> mp.dps = 25
9529 >>> jtheta(1, 7, 0.25, 1); diff(lambda z: jtheta(1, z, 0.25), 7)
9530 1.209857192844475388637236
9531 1.209857192844475388637236
9532 >>> jtheta(1, 7, 0.25, 2); diff(lambda z: jtheta(1, z, 0.25), 7, 2)
9533 -0.2598718791650217206533052
9534 -0.2598718791650217206533052
9535 >>> jtheta(2, 7, 0.25, 1); diff(lambda z: jtheta(2, z, 0.25), 7)
9536 -1.150231437070259644461474
9537 -1.150231437070259644461474
9538 >>> jtheta(2, 7, 0.25, 2); diff(lambda z: jtheta(2, z, 0.25), 7, 2)
9539 -0.6226636990043777445898114
9540 -0.6226636990043777445898114
9541 >>> jtheta(3, 7, 0.25, 1); diff(lambda z: jtheta(3, z, 0.25), 7)
9542 -0.9990312046096634316587882
9543 -0.9990312046096634316587882
9544 >>> jtheta(3, 7, 0.25, 2); diff(lambda z: jtheta(3, z, 0.25), 7, 2)
9545 -0.1530388693066334936151174
9546 -0.1530388693066334936151174
9547 >>> jtheta(4, 7, 0.25, 1); diff(lambda z: jtheta(4, z, 0.25), 7)
9548 0.9820995967262793943571139
9549 0.9820995967262793943571139
9550 >>> jtheta(4, 7, 0.25, 2); diff(lambda z: jtheta(4, z, 0.25), 7, 2)
9551 0.3936902850291437081667755
9552 0.3936902850291437081667755
9554**Possible issues**
9556For `|q| \ge 1` or `\Im(\tau) \le 0`, :func:`~mpmath.jtheta` raises
9557``ValueError``. This exception is also raised for `|q|` extremely
9558close to 1 (or equivalently `\tau` very close to 0), since the
9559series would converge too slowly::
9561 >>> jtheta(1, 10, 0.99999999 * exp(0.5*j))
9562 Traceback (most recent call last):
9563 ...
9564 ValueError: abs(q) > THETA_Q_LIM = 1.000000
9566"""
9568eulernum = r"""
9569Gives the `n`-th Euler number, defined as the `n`-th derivative of
9570`\mathrm{sech}(t) = 1/\cosh(t)` evaluated at `t = 0`. Equivalently, the
9571Euler numbers give the coefficients of the Taylor series
9573.. math ::
9575 \mathrm{sech}(t) = \sum_{n=0}^{\infty} \frac{E_n}{n!} t^n.
9577The Euler numbers are closely related to Bernoulli numbers
9578and Bernoulli polynomials. They can also be evaluated in terms of
9579Euler polynomials (see :func:`~mpmath.eulerpoly`) as `E_n = 2^n E_n(1/2)`.
9581**Examples**
9583Computing the first few Euler numbers and verifying that they
9584agree with the Taylor series::
9586 >>> from mpmath import *
9587 >>> mp.dps = 25; mp.pretty = True
9588 >>> [eulernum(n) for n in range(11)]
9589 [1.0, 0.0, -1.0, 0.0, 5.0, 0.0, -61.0, 0.0, 1385.0, 0.0, -50521.0]
9590 >>> chop(diffs(sech, 0, 10))
9591 [1.0, 0.0, -1.0, 0.0, 5.0, 0.0, -61.0, 0.0, 1385.0, 0.0, -50521.0]
9593Euler numbers grow very rapidly. :func:`~mpmath.eulernum` efficiently
9594computes numerical approximations for large indices::
9596 >>> eulernum(50)
9597 -6.053285248188621896314384e+54
9598 >>> eulernum(1000)
9599 3.887561841253070615257336e+2371
9600 >>> eulernum(10**20)
9601 4.346791453661149089338186e+1936958564106659551331
9603Comparing with an asymptotic formula for the Euler numbers::
9605 >>> n = 10**5
9606 >>> (-1)**(n//2) * 8 * sqrt(n/(2*pi)) * (2*n/(pi*e))**n
9607 3.69919063017432362805663e+436961
9608 >>> eulernum(n)
9609 3.699193712834466537941283e+436961
9611Pass ``exact=True`` to obtain exact values of Euler numbers as integers::
9613 >>> print(eulernum(50, exact=True))
9614 -6053285248188621896314383785111649088103498225146815121
9615 >>> print(eulernum(200, exact=True) % 10**10)
9616 1925859625
9617 >>> eulernum(1001, exact=True)
9618 0
9619"""
9621eulerpoly = r"""
9622Evaluates the Euler polynomial `E_n(z)`, defined by the generating function
9623representation
9625.. math ::
9627 \frac{2e^{zt}}{e^t+1} = \sum_{n=0}^\infty E_n(z) \frac{t^n}{n!}.
9629The Euler polynomials may also be represented in terms of
9630Bernoulli polynomials (see :func:`~mpmath.bernpoly`) using various formulas, for
9631example
9633.. math ::
9635 E_n(z) = \frac{2}{n+1} \left(
9636 B_n(z)-2^{n+1}B_n\left(\frac{z}{2}\right)
9637 \right).
9639Special values include the Euler numbers `E_n = 2^n E_n(1/2)` (see
9640:func:`~mpmath.eulernum`).
9642**Examples**
9644Computing the coefficients of the first few Euler polynomials::
9646 >>> from mpmath import *
9647 >>> mp.dps = 25; mp.pretty = True
9648 >>> for n in range(6):
9649 ... chop(taylor(lambda z: eulerpoly(n,z), 0, n))
9650 ...
9651 [1.0]
9652 [-0.5, 1.0]
9653 [0.0, -1.0, 1.0]
9654 [0.25, 0.0, -1.5, 1.0]
9655 [0.0, 1.0, 0.0, -2.0, 1.0]
9656 [-0.5, 0.0, 2.5, 0.0, -2.5, 1.0]
9658Evaluation for arbitrary `z`::
9660 >>> eulerpoly(2,3)
9661 6.0
9662 >>> eulerpoly(5,4)
9663 423.5
9664 >>> eulerpoly(35, 11111111112)
9665 3.994957561486776072734601e+351
9666 >>> eulerpoly(4, 10+20j)
9667 (-47990.0 - 235980.0j)
9668 >>> eulerpoly(2, '-3.5e-5')
9669 0.000035001225
9670 >>> eulerpoly(3, 0.5)
9671 0.0
9672 >>> eulerpoly(55, -10**80)
9673 -1.0e+4400
9674 >>> eulerpoly(5, -inf)
9675 -inf
9676 >>> eulerpoly(6, -inf)
9677 +inf
9679Computing Euler numbers::
9681 >>> 2**26 * eulerpoly(26,0.5)
9682 -4087072509293123892361.0
9683 >>> eulernum(26)
9684 -4087072509293123892361.0
9686Evaluation is accurate for large `n` and small `z`::
9688 >>> eulerpoly(100, 0.5)
9689 2.29047999988194114177943e+108
9690 >>> eulerpoly(1000, 10.5)
9691 3.628120031122876847764566e+2070
9692 >>> eulerpoly(10000, 10.5)
9693 1.149364285543783412210773e+30688
9694"""
9696spherharm = r"""
9697Evaluates the spherical harmonic `Y_l^m(\theta,\phi)`,
9699.. math ::
9701 Y_l^m(\theta,\phi) = \sqrt{\frac{2l+1}{4\pi}\frac{(l-m)!}{(l+m)!}}
9702 P_l^m(\cos \theta) e^{i m \phi}
9704where `P_l^m` is an associated Legendre function (see :func:`~mpmath.legenp`).
9706Here `\theta \in [0, \pi]` denotes the polar coordinate (ranging
9707from the north pole to the south pole) and `\phi \in [0, 2 \pi]` denotes the
9708azimuthal coordinate on a sphere. Care should be used since many different
9709conventions for spherical coordinate variables are used.
9711Usually spherical harmonics are considered for `l \in \mathbb{N}`,
9712`m \in \mathbb{Z}`, `|m| \le l`. More generally, `l,m,\theta,\phi`
9713are permitted to be complex numbers.
9715.. note ::
9717 :func:`~mpmath.spherharm` returns a complex number, even if the value is
9718 purely real.
9720**Plots**
9722.. literalinclude :: /plots/spherharm40.py
9724`Y_{4,0}`:
9726.. image :: /plots/spherharm40.png
9728`Y_{4,1}`:
9730.. image :: /plots/spherharm41.png
9732`Y_{4,2}`:
9734.. image :: /plots/spherharm42.png
9736`Y_{4,3}`:
9738.. image :: /plots/spherharm43.png
9740`Y_{4,4}`:
9742.. image :: /plots/spherharm44.png
9744**Examples**
9746Some low-order spherical harmonics with reference values::
9748 >>> from mpmath import *
9749 >>> mp.dps = 25; mp.pretty = True
9750 >>> theta = pi/4
9751 >>> phi = pi/3
9752 >>> spherharm(0,0,theta,phi); 0.5*sqrt(1/pi)*expj(0)
9753 (0.2820947917738781434740397 + 0.0j)
9754 (0.2820947917738781434740397 + 0.0j)
9755 >>> spherharm(1,-1,theta,phi); 0.5*sqrt(3/(2*pi))*expj(-phi)*sin(theta)
9756 (0.1221506279757299803965962 - 0.2115710938304086076055298j)
9757 (0.1221506279757299803965962 - 0.2115710938304086076055298j)
9758 >>> spherharm(1,0,theta,phi); 0.5*sqrt(3/pi)*cos(theta)*expj(0)
9759 (0.3454941494713354792652446 + 0.0j)
9760 (0.3454941494713354792652446 + 0.0j)
9761 >>> spherharm(1,1,theta,phi); -0.5*sqrt(3/(2*pi))*expj(phi)*sin(theta)
9762 (-0.1221506279757299803965962 - 0.2115710938304086076055298j)
9763 (-0.1221506279757299803965962 - 0.2115710938304086076055298j)
9765With the normalization convention used, the spherical harmonics are orthonormal
9766on the unit sphere::
9768 >>> sphere = [0,pi], [0,2*pi]
9769 >>> dS = lambda t,p: fp.sin(t) # differential element
9770 >>> Y1 = lambda t,p: fp.spherharm(l1,m1,t,p)
9771 >>> Y2 = lambda t,p: fp.conj(fp.spherharm(l2,m2,t,p))
9772 >>> l1 = l2 = 3; m1 = m2 = 2
9773 >>> fp.chop(fp.quad(lambda t,p: Y1(t,p)*Y2(t,p)*dS(t,p), *sphere))
9774 1.0000000000000007
9775 >>> m2 = 1 # m1 != m2
9776 >>> print(fp.chop(fp.quad(lambda t,p: Y1(t,p)*Y2(t,p)*dS(t,p), *sphere)))
9777 0.0
9779Evaluation is accurate for large orders::
9781 >>> spherharm(1000,750,0.5,0.25)
9782 (3.776445785304252879026585e-102 - 5.82441278771834794493484e-102j)
9784Evaluation works with complex parameter values::
9786 >>> spherharm(1+j, 2j, 2+3j, -0.5j)
9787 (64.44922331113759992154992 + 1981.693919841408089681743j)
9788"""
9790scorergi = r"""
9791Evaluates the Scorer function
9793.. math ::
9795 \operatorname{Gi}(z) =
9796 \operatorname{Ai}(z) \int_0^z \operatorname{Bi}(t) dt +
9797 \operatorname{Bi}(z) \int_z^{\infty} \operatorname{Ai}(t) dt
9799which gives a particular solution to the inhomogeneous Airy
9800differential equation `f''(z) - z f(z) = 1/\pi`. Another
9801particular solution is given by the Scorer Hi-function
9802(:func:`~mpmath.scorerhi`). The two functions are related as
9803`\operatorname{Gi}(z) + \operatorname{Hi}(z) = \operatorname{Bi}(z)`.
9805**Plots**
9807.. literalinclude :: /plots/gi.py
9808.. image :: /plots/gi.png
9809.. literalinclude :: /plots/gi_c.py
9810.. image :: /plots/gi_c.png
9812**Examples**
9814Some values and limits::
9816 >>> from mpmath import *
9817 >>> mp.dps = 25; mp.pretty = True
9818 >>> scorergi(0); 1/(power(3,'7/6')*gamma('2/3'))
9819 0.2049755424820002450503075
9820 0.2049755424820002450503075
9821 >>> diff(scorergi, 0); 1/(power(3,'5/6')*gamma('1/3'))
9822 0.1494294524512754526382746
9823 0.1494294524512754526382746
9824 >>> scorergi(+inf); scorergi(-inf)
9825 0.0
9826 0.0
9827 >>> scorergi(1)
9828 0.2352184398104379375986902
9829 >>> scorergi(-1)
9830 -0.1166722172960152826494198
9832Evaluation for large arguments::
9834 >>> scorergi(10)
9835 0.03189600510067958798062034
9836 >>> scorergi(100)
9837 0.003183105228162961476590531
9838 >>> scorergi(1000000)
9839 0.0000003183098861837906721743873
9840 >>> 1/(pi*1000000)
9841 0.0000003183098861837906715377675
9842 >>> scorergi(-1000)
9843 -0.08358288400262780392338014
9844 >>> scorergi(-100000)
9845 0.02886866118619660226809581
9846 >>> scorergi(50+10j)
9847 (0.0061214102799778578790984 - 0.001224335676457532180747917j)
9848 >>> scorergi(-50-10j)
9849 (5.236047850352252236372551e+29 - 3.08254224233701381482228e+29j)
9850 >>> scorergi(100000j)
9851 (-8.806659285336231052679025e+6474077 + 8.684731303500835514850962e+6474077j)
9853Verifying the connection between Gi and Hi::
9855 >>> z = 0.25
9856 >>> scorergi(z) + scorerhi(z)
9857 0.7287469039362150078694543
9858 >>> airybi(z)
9859 0.7287469039362150078694543
9861Verifying the differential equation::
9863 >>> for z in [-3.4, 0, 2.5, 1+2j]:
9864 ... chop(diff(scorergi,z,2) - z*scorergi(z))
9865 ...
9866 -0.3183098861837906715377675
9867 -0.3183098861837906715377675
9868 -0.3183098861837906715377675
9869 -0.3183098861837906715377675
9871Verifying the integral representation::
9873 >>> z = 0.5
9874 >>> scorergi(z)
9875 0.2447210432765581976910539
9876 >>> Ai,Bi = airyai,airybi
9877 >>> Bi(z)*(Ai(inf,-1)-Ai(z,-1)) + Ai(z)*(Bi(z,-1)-Bi(0,-1))
9878 0.2447210432765581976910539
9880**References**
98821. [DLMF]_ section 9.12: Scorer Functions
9884"""
9886scorerhi = r"""
9887Evaluates the second Scorer function
9889.. math ::
9891 \operatorname{Hi}(z) =
9892 \operatorname{Bi}(z) \int_{-\infty}^z \operatorname{Ai}(t) dt -
9893 \operatorname{Ai}(z) \int_{-\infty}^z \operatorname{Bi}(t) dt
9895which gives a particular solution to the inhomogeneous Airy
9896differential equation `f''(z) - z f(z) = 1/\pi`. See also
9897:func:`~mpmath.scorergi`.
9899**Plots**
9901.. literalinclude :: /plots/hi.py
9902.. image :: /plots/hi.png
9903.. literalinclude :: /plots/hi_c.py
9904.. image :: /plots/hi_c.png
9906**Examples**
9908Some values and limits::
9910 >>> from mpmath import *
9911 >>> mp.dps = 25; mp.pretty = True
9912 >>> scorerhi(0); 2/(power(3,'7/6')*gamma('2/3'))
9913 0.4099510849640004901006149
9914 0.4099510849640004901006149
9915 >>> diff(scorerhi,0); 2/(power(3,'5/6')*gamma('1/3'))
9916 0.2988589049025509052765491
9917 0.2988589049025509052765491
9918 >>> scorerhi(+inf); scorerhi(-inf)
9919 +inf
9920 0.0
9921 >>> scorerhi(1)
9922 0.9722051551424333218376886
9923 >>> scorerhi(-1)
9924 0.2206696067929598945381098
9926Evaluation for large arguments::
9928 >>> scorerhi(10)
9929 455641153.5163291358991077
9930 >>> scorerhi(100)
9931 6.041223996670201399005265e+288
9932 >>> scorerhi(1000000)
9933 7.138269638197858094311122e+289529652
9934 >>> scorerhi(-10)
9935 0.0317685352825022727415011
9936 >>> scorerhi(-100)
9937 0.003183092495767499864680483
9938 >>> scorerhi(100j)
9939 (-6.366197716545672122983857e-9 + 0.003183098861710582761688475j)
9940 >>> scorerhi(50+50j)
9941 (-5.322076267321435669290334e+63 + 1.478450291165243789749427e+65j)
9942 >>> scorerhi(-1000-1000j)
9943 (0.0001591549432510502796565538 - 0.000159154943091895334973109j)
9945Verifying the differential equation::
9947 >>> for z in [-3.4, 0, 2, 1+2j]:
9948 ... chop(diff(scorerhi,z,2) - z*scorerhi(z))
9949 ...
9950 0.3183098861837906715377675
9951 0.3183098861837906715377675
9952 0.3183098861837906715377675
9953 0.3183098861837906715377675
9955Verifying the integral representation::
9957 >>> z = 0.5
9958 >>> scorerhi(z)
9959 0.6095559998265972956089949
9960 >>> Ai,Bi = airyai,airybi
9961 >>> Bi(z)*(Ai(z,-1)-Ai(-inf,-1)) - Ai(z)*(Bi(z,-1)-Bi(-inf,-1))
9962 0.6095559998265972956089949
9964"""
9967stirling1 = r"""
9968Gives the Stirling number of the first kind `s(n,k)`, defined by
9970.. math ::
9972 x(x-1)(x-2)\cdots(x-n+1) = \sum_{k=0}^n s(n,k) x^k.
9974The value is computed using an integer recurrence. The implementation
9975is not optimized for approximating large values quickly.
9977**Examples**
9979Comparing with the generating function::
9981 >>> from mpmath import *
9982 >>> mp.dps = 25; mp.pretty = True
9983 >>> taylor(lambda x: ff(x, 5), 0, 5)
9984 [0.0, 24.0, -50.0, 35.0, -10.0, 1.0]
9985 >>> [stirling1(5, k) for k in range(6)]
9986 [0.0, 24.0, -50.0, 35.0, -10.0, 1.0]
9988Recurrence relation::
9990 >>> n, k = 5, 3
9991 >>> stirling1(n+1,k) + n*stirling1(n,k) - stirling1(n,k-1)
9992 0.0
9994The matrices of Stirling numbers of first and second kind are inverses
9995of each other::
9997 >>> A = matrix(5, 5); B = matrix(5, 5)
9998 >>> for n in range(5):
9999 ... for k in range(5):
10000 ... A[n,k] = stirling1(n,k)
10001 ... B[n,k] = stirling2(n,k)
10002 ...
10003 >>> A * B
10004 [1.0 0.0 0.0 0.0 0.0]
10005 [0.0 1.0 0.0 0.0 0.0]
10006 [0.0 0.0 1.0 0.0 0.0]
10007 [0.0 0.0 0.0 1.0 0.0]
10008 [0.0 0.0 0.0 0.0 1.0]
10010Pass ``exact=True`` to obtain exact values of Stirling numbers as integers::
10012 >>> stirling1(42, 5)
10013 -2.864498971768501633736628e+50
10014 >>> print(stirling1(42, 5, exact=True))
10015 -286449897176850163373662803014001546235808317440000
10017"""
10019stirling2 = r"""
10020Gives the Stirling number of the second kind `S(n,k)`, defined by
10022.. math ::
10024 x^n = \sum_{k=0}^n S(n,k) x(x-1)(x-2)\cdots(x-k+1)
10026The value is computed using integer arithmetic to evaluate a power sum.
10027The implementation is not optimized for approximating large values quickly.
10029**Examples**
10031Comparing with the generating function::
10033 >>> from mpmath import *
10034 >>> mp.dps = 25; mp.pretty = True
10035 >>> taylor(lambda x: sum(stirling2(5,k) * ff(x,k) for k in range(6)), 0, 5)
10036 [0.0, 0.0, 0.0, 0.0, 0.0, 1.0]
10038Recurrence relation::
10040 >>> n, k = 5, 3
10041 >>> stirling2(n+1,k) - k*stirling2(n,k) - stirling2(n,k-1)
10042 0.0
10044Pass ``exact=True`` to obtain exact values of Stirling numbers as integers::
10046 >>> stirling2(52, 10)
10047 2.641822121003543906807485e+45
10048 >>> print(stirling2(52, 10, exact=True))
10049 2641822121003543906807485307053638921722527655
10052"""