cpython-lru_cache-weakref: Doc/library/math.rst annotate

annotate Doc/library/math.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	b36cb4602e21
children	9b3d0bdb9256

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`math` --- Mathematical functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ======================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: math
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Mathematical functions (sin() etc.).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 This module is always available. It provides access to the mathematical
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 functions defined by the C standard.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 These functions cannot be used with complex numbers; use the functions of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 same name from the :mod:`cmath` module if you require support for complex
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 numbers. The distinction between functions which support complex numbers and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 those which don't is made since most users do not want to learn quite as much
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 mathematics as required to understand complex numbers. Receiving an exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 instead of a complex result allows earlier detection of the unexpected complex
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 number used as a parameter, so that the programmer can determine how and why it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 was generated in the first place.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 The following functions are provided by this module. Except when explicitly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 noted otherwise, all return values are floats.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	25 Number-theoretic and representation functions
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	26 ---------------------------------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 .. function:: ceil(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
44488 94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44480 diff changeset	30 Return the ceiling of x as a float, the smallest integer value greater than or
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44480 diff changeset	31 equal to x.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
44440 6208b17d0dbe Added copysign(x, y) function to the math module Christian Heimes <christian@cheimes.de> parents: 44437 diff changeset	34 .. function:: copysign(x, y)
6208b17d0dbe Added copysign(x, y) function to the math module Christian Heimes <christian@cheimes.de> parents: 44437 diff changeset	35
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	36 Return x with the sign of y. On a platform that supports
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	37 signed zeros, ``copysign(1.0, -0.0)`` returns -1.0.
44440 6208b17d0dbe Added copysign(x, y) function to the math module Christian Heimes <christian@cheimes.de> parents: 44437 diff changeset	38
44480 57c7d42f6cde Fix markup Andrew M. Kuchling <amk@amk.ca> parents: 44440 diff changeset	39 .. versionadded:: 2.6
44440 6208b17d0dbe Added copysign(x, y) function to the math module Christian Heimes <christian@cheimes.de> parents: 44437 diff changeset	40
6208b17d0dbe Added copysign(x, y) function to the math module Christian Heimes <christian@cheimes.de> parents: 44437 diff changeset	41
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 .. function:: fabs(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 Return the absolute value of x.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	46
47529 6428c4f1ae09 Issue #2138: Add math.factorial(). Raymond Hettinger <python@rcn.com> parents: 47215 diff changeset	47 .. function:: factorial(x)
6428c4f1ae09 Issue #2138: Add math.factorial(). Raymond Hettinger <python@rcn.com> parents: 47215 diff changeset	48
47758 ab12e3ad2e66 Typo fix Mark Dickinson <dickinsm@gmail.com> parents: 47529 diff changeset	49 Return x factorial. Raises :exc:`ValueError` if x is not integral or
47529 6428c4f1ae09 Issue #2138: Add math.factorial(). Raymond Hettinger <python@rcn.com> parents: 47215 diff changeset	50 is negative.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	52 .. versionadded:: 2.6
b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	53
b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	54
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 .. function:: floor(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
44488 94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44480 diff changeset	57 Return the floor of x as a float, the largest integer value less than or equal
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44480 diff changeset	58 to x.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 .. function:: fmod(x, y)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 Return ``fmod(x, y)``, as defined by the platform C library. Note that the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 Python expression ``x % y`` may not return the same result. The intent of the C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 precision) equal to ``x - ny`` for some integer n* such that the result has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 the same sign as x and magnitude less than ``abs(y)``. Python's ``x % y``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 returns a result with the sign of y instead, and may not be exactly computable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 for float arguments. For example, ``fmod(-1e-100, 1e100)`` is ``-1e-100``, but
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 the result of Python's ``-1e-100 % 1e100`` is ``1e100-1e-100``, which cannot be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 represented exactly as a float, and rounds to the surprising ``1e100``. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 this reason, function :func:`fmod` is generally preferred when working with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 floats, while Python's ``x % y`` is preferred when working with integers.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 .. function:: frexp(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 Return the mantissa and exponent of x as the pair ``(m, e)``. m is a float
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 and e is an integer such that ``x == m * 2*e`` exactly. If x* is zero,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 apart" the internal representation of a float in a portable way.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
48101 8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	84 .. function:: fsum(iterable)
8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	85
8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	86 Return an accurate floating point sum of values in the iterable. Avoids
51729 ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	87 loss of precision by tracking multiple intermediate partial sums::
48101 8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	88
51729 ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	89 >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
57428 337ebb829b8c Fix some documentation examples involving the repr of a float. Mark Dickinson <dickinsm@gmail.com> parents: 56671 diff changeset	90 0.9999999999999999
51729 ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	91 >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	92 1.0
48105 67d177aab8a7 Add note about problems with math.fsum on x86 hardware. Mark Dickinson <dickinsm@gmail.com> parents: 48101 diff changeset	93
51729 ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	94 The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	95 typical case where the rounding mode is half-even. On some non-Windows
ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	96 builds, the underlying C library uses extended precision addition and may
ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	97 occasionally double-round an intermediate sum causing it to be off in its
ea47cef67837 Add an example for math.fsum() and elaborate on the accurary note. Raymond Hettinger <python@rcn.com> parents: 50522 diff changeset	98 least significant bit.
48105 67d177aab8a7 Add note about problems with math.fsum on x86 hardware. Mark Dickinson <dickinsm@gmail.com> parents: 48101 diff changeset	99
51733 f0eac452a6ca Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51729 diff changeset	100 For further discussion and two alternative approaches, see the `ASPN cookbook
f0eac452a6ca Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51729 diff changeset	101 recipes for accurate floating point summation
f0eac452a6ca Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51729 diff changeset	102 <http://code.activestate.com/recipes/393090/>`_\.
f0eac452a6ca Add links to helpful external resources. Raymond Hettinger <python@rcn.com> parents: 51729 diff changeset	103
48101 8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	104 .. versionadded:: 2.6
8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	105
8d05dda735f8 Rename math.sum to math.fsum Mark Dickinson <dickinsm@gmail.com> parents: 47759 diff changeset	106
44437 968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	107 .. function:: isinf(x)
968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	108
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	109 Check if the float x is positive or negative infinity.
44437 968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	110
44480 57c7d42f6cde Fix markup Andrew M. Kuchling <amk@amk.ca> parents: 44440 diff changeset	111 .. versionadded:: 2.6
44437 968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	112
968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	113
968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	114 .. function:: isnan(x)
968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	115
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	116 Check if the float x is a NaN (not a number). For more information
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	117 on NaNs, see the IEEE 754 standards.
44437 968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	118
44480 57c7d42f6cde Fix markup Andrew M. Kuchling <amk@amk.ca> parents: 44440 diff changeset	119 .. versionadded:: 2.6
44437 968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	120
968bda81e6c8 Added math.isinf() and math.isnan() Christian Heimes <christian@cheimes.de> parents: 44432 diff changeset	121
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 .. function:: ldexp(x, i)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 Return ``x * (2**i)``. This is essentially the inverse of function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 :func:`frexp`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 .. function:: modf(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	130 Return the fractional and integer parts of x. Both results carry the sign
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	131 of x and are floats.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	133
45079 492b302aded6 Move __builtins__.trunc() to math.trunc() per Jeffrey Yasskin <jyasskin@gmail.com> parents: 44495 diff changeset	134 .. function:: trunc(x)
492b302aded6 Move __builtins__.trunc() to math.trunc() per Jeffrey Yasskin <jyasskin@gmail.com> parents: 44495 diff changeset	135
492b302aded6 Move __builtins__.trunc() to math.trunc() per Jeffrey Yasskin <jyasskin@gmail.com> parents: 44495 diff changeset	136 Return the :class:`Real` value x truncated to an :class:`Integral` (usually
62676 6d0dedb3a24e Merged revisions 82429 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 62669 diff changeset	137 a long integer). Uses the ``__trunc__`` method.
45079 492b302aded6 Move __builtins__.trunc() to math.trunc() per Jeffrey Yasskin <jyasskin@gmail.com> parents: 44495 diff changeset	138
492b302aded6 Move __builtins__.trunc() to math.trunc() per Jeffrey Yasskin <jyasskin@gmail.com> parents: 44495 diff changeset	139 .. versionadded:: 2.6
492b302aded6 Move __builtins__.trunc() to math.trunc() per Jeffrey Yasskin <jyasskin@gmail.com> parents: 44495 diff changeset	140
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	141
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 Note that :func:`frexp` and :func:`modf` have a different call/return pattern
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 than their C equivalents: they take a single argument and return a pair of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 values, rather than returning their second return value through an 'output
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 parameter' (there is no such thing in Python).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 floating-point numbers of sufficiently large magnitude are exact integers.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 Python floats typically carry no more than 53 bits of precision (the same as the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 platform C double type), in which case any float x with ``abs(x) >= 2**52``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 necessarily has no fractional bits.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	153
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	154 Power and logarithmic functions
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	155 -------------------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 .. function:: exp(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 Return ``e**x``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
57756 b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	162 .. function:: expm1(x)
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	163
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	164 Return ``e*x - 1``. For small floats x*, the subtraction in
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	165 ``exp(x) - 1`` can result in a significant loss of precision; the
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	166 :func:`expm1` function provides a way to compute this quantity to
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	167 full precision::
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	168
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	169 >>> from math import exp, expm1
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	170 >>> exp(1e-5) - 1 # gives result accurate to 11 places
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	171 1.0000050000069649e-05
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	172 >>> expm1(1e-5) # result accurate to full precision
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	173 1.0000050000166668e-05
b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	174
57769 d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	175 .. versionadded:: 2.7
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	176
57756 b206ad8cf5bf Issue #3366: Add expm1 function to math module. Thanks Eric Smith for Mark Dickinson <dickinsm@gmail.com> parents: 57655 diff changeset	177
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 .. function:: log(x[, base])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 51733 diff changeset	180 With one argument, return the natural logarithm of x (to base e).
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 51733 diff changeset	181
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 51733 diff changeset	182 With two arguments, return the logarithm of x to the given base,
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 51733 diff changeset	183 calculated as ``log(x)/log(base)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 .. versionchanged:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 base argument added.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188
46473 5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	189 .. function:: log1p(x)
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	190
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	191 Return the natural logarithm of 1+x (base e). The
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	192 result is calculated in a way which is accurate for x near zero.
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	193
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	194 .. versionadded:: 2.6
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	195
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	196
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 .. function:: log10(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 51733 diff changeset	199 Return the base-10 logarithm of x. This is usually more accurate
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 51733 diff changeset	200 than ``log(x, 10)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 .. function:: pow(x, y)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
46495 f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	205 Return ``x`` raised to the power ``y``. Exceptional cases follow
f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	206 Annex 'F' of the C99 standard as far as possible. In particular,
f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	207 ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	208 when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite,
f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	209 ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	210 is undefined, and raises :exc:`ValueError`.
46473 5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	211
5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	212 .. versionchanged:: 2.6
46495 f641e505fff4 Correct documentation for math.pow; Mark Dickinson <dickinsm@gmail.com> parents: 46473 diff changeset	213 The outcome of ``1nan`` and ``nan0`` was undefined.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 .. function:: sqrt(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 Return the square root of x.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	220
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	221 Trigonometric functions
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	222 -----------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 .. function:: acos(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 Return the arc cosine of x, in radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 .. function:: asin(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 Return the arc sine of x, in radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 .. function:: atan(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 Return the arc tangent of x, in radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 .. function:: atan2(y, x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 The vector in the plane from the origin to point ``(x, y)`` makes this angle
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 with the positive X axis. The point of :func:`atan2` is that the signs of both
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 inputs are known to it, so it can compute the correct quadrant for the angle.
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	245 For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 -1)`` is ``-3*pi/4``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 .. function:: cos(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 Return the cosine of x radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 .. function:: hypot(x, y)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 Return the Euclidean norm, ``sqrt(xx + yy)``. This is the length of the vector
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 from the origin to point ``(x, y)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 .. function:: sin(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 Return the sine of x radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 .. function:: tan(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 Return the tangent of x radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	269
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	270 Angular conversion
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	271 ------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 .. function:: degrees(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 Converts angle x from radians to degrees.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 .. function:: radians(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 Converts angle x from degrees to radians.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
47759 b4d823483421 Add versionadded tags to new math functions. Georg Brandl <georg@python.org> parents: 47758 diff changeset	282
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	283 Hyperbolic functions
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	284 --------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
46496 35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	286 .. function:: acosh(x)
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	287
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	288 Return the inverse hyperbolic cosine of x.
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	289
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	290 .. versionadded:: 2.6
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	291
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	292
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	293 .. function:: asinh(x)
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	294
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	295 Return the inverse hyperbolic sine of x.
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	296
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	297 .. versionadded:: 2.6
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	298
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	299
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	300 .. function:: atanh(x)
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	301
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	302 Return the inverse hyperbolic tangent of x.
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	303
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	304 .. versionadded:: 2.6
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	305
35bf8012a376 Move asinh documentation to the proper place. Mark Dickinson <dickinsm@gmail.com> parents: 46495 diff changeset	306
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 .. function:: cosh(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 Return the hyperbolic cosine of x.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 .. function:: sinh(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 Return the hyperbolic sine of x.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 .. function:: tanh(x)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 Return the hyperbolic tangent of x.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
46473 5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	321
56268 b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	322 Special functions
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	323 -----------------
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	324
57769 d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	325 .. function:: erf(x)
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	326
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	327 Return the error function at x.
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	328
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	329 .. versionadded:: 2.7
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	330
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	331
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	332 .. function:: erfc(x)
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	333
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	334 Return the complementary error function at x.
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	335
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	336 .. versionadded:: 2.7
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	337
d350afc337dc Issue #3366: Add error function and complementary error function to Mark Dickinson <dickinsm@gmail.com> parents: 57756 diff changeset	338
56268 b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	339 .. function:: gamma(x)
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	340
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	341 Return the Gamma function at x.
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	342
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	343 .. versionadded:: 2.7
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	344
b50dd17dfe26 Issue #3366: Add gamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 55790 diff changeset	345
57655 cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	346 .. function:: lgamma(x)
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	347
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	348 Return the natural logarithm of the absolute value of the Gamma
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	349 function at x.
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	350
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	351 .. versionadded:: 2.7
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	352
cb22eaee86c9 Issue #3366: Add lgamma function to math module. Mark Dickinson <dickinsm@gmail.com> parents: 57428 diff changeset	353
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	354 Constants
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48904 diff changeset	355 ---------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 .. data:: pi
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	359 The mathematical constant π = 3.141592..., to available precision.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 .. data:: e
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	364 The mathematical constant e = 2.718281..., to available precision.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
46473 5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	366
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	367 .. impl-detail::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 The :mod:`math` module consists mostly of thin wrappers around the platform C
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	370 math library functions. Behavior in exceptional cases follows Annex F of
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	371 the C99 standard where appropriate. The current implementation will raise
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	372 :exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)``
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	373 (where C99 Annex F recommends signaling invalid operation or divide-by-zero),
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	374 and :exc:`OverflowError` for results that overflow (for example,
60559 89752c03f342 Merged revisions 79875 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 60427 diff changeset	375 ``exp(1000.0)``). A NaN will not be returned from any of the functions
89752c03f342 Merged revisions 79875 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 60427 diff changeset	376 above unless one or more of the input arguments was a NaN; in that case,
89752c03f342 Merged revisions 79875 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 60427 diff changeset	377 most functions will return a NaN, but (again following C99 Annex F) there
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	378 are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	379 ``hypot(float('nan'), float('inf'))``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380
60427 1a6f3d36bbd9 Merged revisions 79871 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 60416 diff changeset	381 Note that Python makes no effort to distinguish signaling NaNs from
1a6f3d36bbd9 Merged revisions 79871 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 60416 diff changeset	382 quiet NaNs, and behavior for signaling NaNs remains unspecified.
1a6f3d36bbd9 Merged revisions 79871 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 60416 diff changeset	383 Typical behavior is to treat all NaNs as though they were quiet.
46473 5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	384
46958 e64039bbfe26 Fix markup. Georg Brandl <georg@python.org> parents: 46496 diff changeset	385 .. versionchanged:: 2.6
60416 01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	386 Behavior in special cases now aims to follow C99 Annex F. In earlier
01c1aa3a49a7 Merged revisions 79858 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 56824 diff changeset	387 versions of Python the behavior in special cases was loosely specified.
46473 5bc7b20dc04a I finally got the time to update and merge Mark's and my trunk-math branch. The patch is collaborated work of Mark Dickinson and me. It was mostly done a few months ago. The patch fixes a lot of loose ends and edge cases related to operations with NaN, INF, very small values and complex math. Christian Heimes <christian@cheimes.de> parents: 45079 diff changeset	388
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 Module :mod:`cmath`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 Complex number versions of many of these functions.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/math.rst @ 79675:c0a2294de787 2.7