diff options
| -rw-r--r-- | Doc/lib/libmath.tex | 163 | ||||
| -rw-r--r-- | Misc/NEWS | 3 |
2 files changed, 101 insertions, 65 deletions
diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex index a9cbc77..3590467 100644 --- a/Doc/lib/libmath.tex +++ b/Doc/lib/libmath.tex @@ -18,42 +18,13 @@ number used as a parameter, so that the programmer can determine how and why it was generated in the first place. The following functions are provided by this module. Except -when explicitly noted otherwise, all return values are floats: +when explicitly noted otherwise, all return values are floats. -\begin{funcdesc}{acos}{x} -Return the arc cosine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{asin}{x} -Return the arc sine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{atan}{x} -Return the arc tangent of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{atan2}{y, x} -Return \code{atan(\var{y} / \var{x})}. -\end{funcdesc} +Number-theoretic and representation functions: \begin{funcdesc}{ceil}{x} -Return the ceiling of \var{x} as a float. -\end{funcdesc} - -\begin{funcdesc}{cos}{x} -Return the cosine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{cosh}{x} -Return the hyperbolic cosine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{degrees}{x} -Converts angle \var{x} from radians to degrees. -\end{funcdesc} - -\begin{funcdesc}{exp}{x} -Return \code{e**\var{x}}. +Return the ceiling of \var{x} as a float, the smallest integer value +greater than or equal to \var{x}. \end{funcdesc} \begin{funcdesc}{fabs}{x} @@ -61,35 +32,63 @@ Return the absolute value of \var{x}. \end{funcdesc} \begin{funcdesc}{floor}{x} -Return the floor of \var{x} as a float. +Return the floor of \var{x} as a float, the largest integer value +less than or equal to \var{x}. \end{funcdesc} \begin{funcdesc}{fmod}{x, y} Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library. Note that the Python expression \code{\var{x} \%\ \var{y}} may not return -the same result. +the same result. The intent of the C standard is that +\code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite +precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer +\var{n} such that the result has the same sign as \var{x} and +magnitude less than \code{abs(\var{y})}. Python's +\code{\var{x} \%\ \var{y}} returns a result with the sign of +\var{y} instead, and may not be exactly computable for float arguments. +For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the +result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which +cannot be represented exactly as a float, and rounds to the surprising +\code{1e100}. For this reason, function \function{fmod()} is generally +preferred when working with floats, while Python's +\code{\var{x} \%\ \var{y}} is preferred when working with integers. \end{funcdesc} \begin{funcdesc}{frexp}{x} -% Blessed by Tim. Return the mantissa and exponent of \var{x} as the pair \code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an -integer such that \code{\var{x} == \var{m} * 2**\var{e}}. +integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly. If \var{x} is zero, returns \code{(0.0, 0)}, otherwise -\code{0.5 <= abs(\var{m}) < 1}. +\code{0.5 <= abs(\var{m}) < 1}. This is used to "pick apart" the +internal representation of a float in a portable way. \end{funcdesc} -\begin{funcdesc}{hypot}{x, y} -Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}. +\begin{funcdesc}{ldexp}{x, i} +Return \code{\var{x} * (2**\var{i})}. This is essentially the inverse of +function \function{frexp()}. \end{funcdesc} -\begin{funcdesc}{ldexp}{x, i} -Return \code{\var{x} * (2**\var{i})}. +\begin{funcdesc}{modf}{x} +Return the fractional and integer parts of \var{x}. Both results +carry the sign of \var{x}, and both are floats. +\end{funcdesc} + +Note that \function{frexp()} and \function{modf()} have a different +call/return pattern than their C equivalents: they take a single +argument and return a pair of values, rather than returning their +second return value through an `output parameter' (there is no such +thing in Python). + +Power and logarithmic functions: + +\begin{funcdesc}{exp}{x} +Return \code{e**\var{x}}. \end{funcdesc} \begin{funcdesc}{log}{x\optional{, base}} -Returns the logarithm of \var{x} to the given \var{base}. -If the \var{base} is not specified, returns the natural logarithm of \var{x}. +Return the logarithm of \var{x} to the given \var{base}. +If the \var{base} is not specified, return the natural logarithm of \var{x} +(that is, the logarithm to base \emph{e}). \versionchanged[\var{base} argument added]{2.3} \end{funcdesc} @@ -97,45 +96,81 @@ If the \var{base} is not specified, returns the natural logarithm of \var{x}. Return the base-10 logarithm of \var{x}. \end{funcdesc} -\begin{funcdesc}{modf}{x} -Return the fractional and integer parts of \var{x}. Both results -carry the sign of \var{x}. The integer part is returned as a float. -\end{funcdesc} - \begin{funcdesc}{pow}{x, y} Return \code{\var{x}**\var{y}}. \end{funcdesc} -\begin{funcdesc}{radians}{x} -Converts angle \var{x} from degrees to radians. +\begin{funcdesc}{sqrt}{x} +Return the square root of \var{x}. \end{funcdesc} -\begin{funcdesc}{sin}{x} -Return the sine of \var{x}. +Trigonometric functions: + +\begin{funcdesc}{acos}{x} +Return the arc cosine of \var{x}, in radians. \end{funcdesc} -\begin{funcdesc}{sinh}{x} -Return the hyperbolic sine of \var{x}. +\begin{funcdesc}{asin}{x} +Return the arc sine of \var{x}, in radians. \end{funcdesc} -\begin{funcdesc}{sqrt}{x} -Return the square root of \var{x}. +\begin{funcdesc}{atan}{x} +Return the arc tangent of \var{x}, in radians. +\end{funcdesc} + +\begin{funcdesc}{atan2}{y, x} +Return \code{atan(\var{y} / \var{x})}, in radians. +The result is between \code{-pi} and \code{pi}. +The vector in the plane from the origin to point \code{(\var{x}, \var{y})} +makes this angle with the positive X axis. +The point of \function{atan2()} is that the signs of both inputs are +known to it, so it can compute the correct quadrant for the angle. +For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4}, +but \code{atan2(-1, -1)} is \code{-3*pi/4}. +\end{funcdesc} + +\begin{funcdesc}{cos}{x} +Return the cosine of \var{x} radians. +\end{funcdesc} + +\begin{funcdesc}{hypot}{x, y} +Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}. +This is the length of the vector from the origin to point +\code{(\var{x}, \var{y})}. +\end{funcdesc} + +\begin{funcdesc}{sin}{x} +Return the sine of \var{x} radians. \end{funcdesc} \begin{funcdesc}{tan}{x} -Return the tangent of \var{x}. +Return the tangent of \var{x} radians. +\end{funcdesc} + +Angular conversion: + +\begin{funcdesc}{degrees}{x} +Converts angle \var{x} from radians to degrees. +\end{funcdesc} + +\begin{funcdesc}{radians}{x} +Converts angle \var{x} from degrees to radians. +\end{funcdesc} + +Hyerbolic functions: + +\begin{funcdesc}{cosh}{x} +Return the hyperbolic cosine of \var{x}. +\end{funcdesc} + +\begin{funcdesc}{sinh}{x} +Return the hyperbolic sine of \var{x}. \end{funcdesc} \begin{funcdesc}{tanh}{x} Return the hyperbolic tangent of \var{x}. \end{funcdesc} -Note that \function{frexp()} and \function{modf()} have a different -call/return pattern than their C equivalents: they take a single -argument and return a pair of values, rather than returning their -second return value through an `output parameter' (there is no such -thing in Python). - The module also defines two mathematical constants: \begin{datadesc}{pi} @@ -139,7 +139,7 @@ C API Documentation ------------- -Improved the tutorial on creating types in C. +- Improved the tutorial on creating types in C. - point out the importance of reassigning data members before assigning thier values @@ -148,6 +148,7 @@ Improved the tutorial on creating types in C. - mention the labor saving Py_VISIT and Py_CLEAR macros. +- Major rewrite of the math module docs, to address common confusions. New platforms ------------- |