Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libmath.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents d5c97d69dfc7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{math} ---
10646
e09f19441136 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9607
diff changeset
2 Mathematical functions}
e09f19441136 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9607
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{builtin}{math}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
5 \modulesynopsis{Mathematical functions (\function{sin()} etc.).}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
10646
e09f19441136 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9607
diff changeset
7 This module is always available. It provides access to the
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
8 mathematical functions defined by the C standard.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
9
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
10 These functions cannot be used with complex numbers; use the functions
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
11 of the same name from the \refmodule{cmath} module if you require
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
12 support for complex numbers. The distinction between functions which
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
13 support complex numbers and those which don't is made since most users
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
14 do not want to learn quite as much mathematics as required to
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
15 understand complex numbers. Receiving an exception instead of a
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
16 complex result allows earlier detection of the unexpected complex
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
17 number used as a parameter, so that the programmer can determine how
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
18 and why it was generated in the first place.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10646
diff changeset
19
28872
6392e8437588 Reworded fabs() for consistency with the others. Noted that all
Tim Peters <tim.peters@gmail.com>
parents: 28859
diff changeset
20 The following functions are provided by this module. Except
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
21 when explicitly noted otherwise, all return values are floats.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
22
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
23 Number-theoretic and representation functions:
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
24
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
25 \begin{funcdesc}{ceil}{x}
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
26 Return the ceiling of \var{x} as a float, the smallest integer value
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
27 greater than or equal to \var{x}.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
28 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
29
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
30 \begin{funcdesc}{fabs}{x}
28872
6392e8437588 Reworded fabs() for consistency with the others. Noted that all
Tim Peters <tim.peters@gmail.com>
parents: 28859
diff changeset
31 Return the absolute value of \var{x}.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
32 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
33
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
34 \begin{funcdesc}{floor}{x}
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
35 Return the floor of \var{x} as a float, the largest integer value
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
36 less than or equal to \var{x}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 \end{funcdesc}
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
38
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
39 \begin{funcdesc}{fmod}{x, y}
14616
284508c653c7 Fixed legit gripe from c.l.py that math.fmod docs aren't confusing enough.
Tim Peters <tim.peters@gmail.com>
parents: 13912
diff changeset
40 Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
284508c653c7 Fixed legit gripe from c.l.py that math.fmod docs aren't confusing enough.
Tim Peters <tim.peters@gmail.com>
parents: 13912
diff changeset
41 Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
42 the same result. The intent of the C standard is that
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
43 \code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
44 precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
45 \var{n} such that the result has the same sign as \var{x} and
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
46 magnitude less than \code{abs(\var{y})}. Python's
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
47 \code{\var{x} \%\ \var{y}} returns a result with the sign of
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
48 \var{y} instead, and may not be exactly computable for float arguments.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
49 For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
50 result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
51 cannot be represented exactly as a float, and rounds to the surprising
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
52 \code{1e100}. For this reason, function \function{fmod()} is generally
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
53 preferred when working with floats, while Python's
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
54 \code{\var{x} \%\ \var{y}} is preferred when working with integers.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
55 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
56
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
57 \begin{funcdesc}{frexp}{x}
13314
03aa26819ac2 Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents: 12714
diff changeset
58 Return the mantissa and exponent of \var{x} as the pair
03aa26819ac2 Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents: 12714
diff changeset
59 \code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
60 integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly.
13314
03aa26819ac2 Tim-blessed documentation for math.frexp().
Fred Drake <fdrake@acm.org>
parents: 12714
diff changeset
61 If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
62 \code{0.5 <= abs(\var{m}) < 1}. This is used to "pick apart" the
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
63 internal representation of a float in a portable way.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
64 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
65
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
66 \begin{funcdesc}{ldexp}{x, i}
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
67 Return \code{\var{x} * (2**\var{i})}. This is essentially the inverse of
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
68 function \function{frexp()}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
69 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
70
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
71 \begin{funcdesc}{modf}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
72 Return the fractional and integer parts of \var{x}. Both results
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
73 carry the sign of \var{x}, and both are floats.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
74 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
75
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
76 Note that \function{frexp()} and \function{modf()} have a different
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
77 call/return pattern than their C equivalents: they take a single
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
78 argument and return a pair of values, rather than returning their
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
79 second return value through an `output parameter' (there is no such
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
80 thing in Python).
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
81
32812
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
82 For the \function{ceil()}, \function{floor()}, and \function{modf()}
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
83 functions, note that \emph{all} floating-point numbers of sufficiently
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
84 large magnitude are exact integers. Python floats typically carry no more
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
85 than 53 bits of precision (the same as the platform C double type), in
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
86 which case any float \var{x} with \code{abs(\var{x}) >= 2**52}
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
87 necessarily has no fractional bits.
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
88
d5c97d69dfc7 Explain that most floats are actually integers. This is a common confusion
Tim Peters <tim.peters@gmail.com>
parents: 32811
diff changeset
89
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
90 Power and logarithmic functions:
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
91
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
92 \begin{funcdesc}{exp}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
93 Return \code{e**\var{x}}.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
94 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
95
26661
b12e326b4ea2 Apply SF patch 652930: Add optional base argument to math.log(x[, base]).
Raymond Hettinger <python@rcn.com>
parents: 23425
diff changeset
96 \begin{funcdesc}{log}{x\optional{, base}}
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
97 Return the logarithm of \var{x} to the given \var{base}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
98 If the \var{base} is not specified, return the natural logarithm of \var{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
99 (that is, the logarithm to base \emph{e}).
26661
b12e326b4ea2 Apply SF patch 652930: Add optional base argument to math.log(x[, base]).
Raymond Hettinger <python@rcn.com>
parents: 23425
diff changeset
100 \versionchanged[\var{base} argument added]{2.3}
7157
a6fa9f3cad13 Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents: 7048
diff changeset
101 \end{funcdesc}
a6fa9f3cad13 Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents: 7048
diff changeset
102
a6fa9f3cad13 Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents: 7048
diff changeset
103 \begin{funcdesc}{log10}{x}
a6fa9f3cad13 Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents: 7048
diff changeset
104 Return the base-10 logarithm of \var{x}.
a6fa9f3cad13 Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents: 7048
diff changeset
105 \end{funcdesc}
a6fa9f3cad13 Added descriptions for log() and log10().
Fred Drake <fdrake@acm.org>
parents: 7048
diff changeset
106
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
107 \begin{funcdesc}{pow}{x, y}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
108 Return \code{\var{x}**\var{y}}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
109 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
110
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
111 \begin{funcdesc}{sqrt}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
112 Return the square root of \var{x}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
113 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
114
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
115 Trigonometric functions:
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
116
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
117 \begin{funcdesc}{acos}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
118 Return the arc cosine of \var{x}, in radians.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
119 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
120
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
121 \begin{funcdesc}{asin}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
122 Return the arc sine of \var{x}, in radians.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
123 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
124
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
125 \begin{funcdesc}{atan}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
126 Return the arc tangent of \var{x}, in radians.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
127 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
128
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
129 \begin{funcdesc}{atan2}{y, x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
130 Return \code{atan(\var{y} / \var{x})}, in radians.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
131 The result is between \code{-pi} and \code{pi}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
132 The vector in the plane from the origin to point \code{(\var{x}, \var{y})}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
133 makes this angle with the positive X axis.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
134 The point of \function{atan2()} is that the signs of both inputs are
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
135 known to it, so it can compute the correct quadrant for the angle.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
136 For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4},
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
137 but \code{atan2(-1, -1)} is \code{-3*pi/4}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
138 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
139
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
140 \begin{funcdesc}{cos}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
141 Return the cosine of \var{x} radians.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
142 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
143
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
144 \begin{funcdesc}{hypot}{x, y}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
145 Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
146 This is the length of the vector from the origin to point
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
147 \code{(\var{x}, \var{y})}.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
148 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
149
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
150 \begin{funcdesc}{sin}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
151 Return the sine of \var{x} radians.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
152 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
153
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
154 \begin{funcdesc}{tan}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
155 Return the tangent of \var{x} radians.
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
156 \end{funcdesc}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
157
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
158 Angular conversion:
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
159
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
160 \begin{funcdesc}{degrees}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
161 Converts angle \var{x} from radians to degrees.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
162 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
163
23425
62403b93f470 Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents: 15602
diff changeset
164 \begin{funcdesc}{radians}{x}
62403b93f470 Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents: 15602
diff changeset
165 Converts angle \var{x} from degrees to radians.
62403b93f470 Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents: 15602
diff changeset
166 \end{funcdesc}
62403b93f470 Added degrees() and radians() to mathmodule. Closing patch 552452 and
Raymond Hettinger <python@rcn.com>
parents: 15602
diff changeset
167
32811
6e79dea85189 Typo in new docs.
Tim Peters <tim.peters@gmail.com>
parents: 32808
diff changeset
168 Hyperbolic functions:
32808
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
169
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
170 \begin{funcdesc}{cosh}{x}
edbaf610227b SF bug 996392: math and cmath docs don't specify radians
Tim Peters <tim.peters@gmail.com>
parents: 28872
diff changeset
171 Return the hyperbolic cosine of \var{x}.
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
172 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
173
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
174 \begin{funcdesc}{sinh}{x}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
175 Return the hyperbolic sine of \var{x}.
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
176 \end{funcdesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
177
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
178 \begin{funcdesc}{tanh}{x}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
179 Return the hyperbolic tangent of \var{x}.
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
180 \end{funcdesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 The module also defines two mathematical constants:
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
183
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 \begin{datadesc}{pi}
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
185 The mathematical constant \emph{pi}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 \end{datadesc}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 3375
diff changeset
187
6363
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
188 \begin{datadesc}{e}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
189 The mathematical constant \emph{e}.
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
190 \end{datadesc}
0c74688bc1ff Fixed up formatting.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
191
28855
b62d87816976 Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents: 26684
diff changeset
192 \begin{notice}
28859
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
193 The \module{math} module consists mostly of thin wrappers around
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
194 the platform C math library functions. Behavior in exceptional cases is
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
195 loosely specified by the C standards, and Python inherits much of its
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
196 math-function error-reporting behavior from the platform C
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
197 implementation. As a result,
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
198 the specific exceptions raised in error cases (and even whether some
28855
b62d87816976 Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents: 26684
diff changeset
199 arguments are considered to be exceptional at all) are not defined in any
b62d87816976 Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents: 26684
diff changeset
200 useful cross-platform or cross-release way. For example, whether
b62d87816976 Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents: 26684
diff changeset
201 \code{math.log(0)} returns \code{-Inf} or raises \exception{ValueError} or
28859
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
202 \exception{OverflowError} isn't defined, and in
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
203 cases where \code{math.log(0)} raises \exception{OverflowError},
103faa0c2e1e Clarified new text about math exceptions.
Tim Peters <tim.peters@gmail.com>
parents: 28855
diff changeset
204 \code{math.log(0L)} may raise \exception{ValueError} instead.
28855
b62d87816976 Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents: 26684
diff changeset
205 \end{notice}
b62d87816976 Add note about platform-specific behavior arising from discussion on bug
Skip Montanaro <skip@pobox.com>
parents: 26684
diff changeset
206
6485
2f258162aae2 Restore the \seealso formatting that got lost when I updated the math
Fred Drake <fdrake@acm.org>
parents: 6363
diff changeset
207 \begin{seealso}
2f258162aae2 Restore the \seealso formatting that got lost when I updated the math
Fred Drake <fdrake@acm.org>
parents: 6363
diff changeset
208 \seemodule{cmath}{Complex number versions of many of these functions.}
2f258162aae2 Restore the \seealso formatting that got lost when I updated the math
Fred Drake <fdrake@acm.org>
parents: 6363
diff changeset
209 \end{seealso}